C++ std::filesystem遍历目录与文件操作的跨平台方案

在C++17之前，处理文件路径、遍历目录或进行跨平台文件操作往往需要依赖操作系统特定的API或第三方库。C++17引入的 std::filesystem 库彻底改变了这一局面，它提供了一个标准化、跨平台（Windows、Linux、macOS）的接口来操作文件系统。本指南将手把手教你如何使用它，实现高效、可靠的目录遍历与文件操作。

1. 设置编译环境与基础准备

要使用 std::filesystem，首先需要确保你的编译环境支持C++17，并正确链接了文件系统库。

1. 检查编译器版本：确保你的编译器支持C++17。主流编译器如 GCC 8+、Clang 7+、MSVC 19.14+ 都已支持。

2. 包含头文件：在你的源代码文件顶部，添加以下头文件：

   #include <filesystem>
   #include <iostream>
   #include <string>
   // 为了方便，通常会设置一个命名空间别名
   namespace fs = std::filesystem;

3. 配置编译选项：根据你的平台和编译器，添加相应的编译标志。

   • Linux/macOS (使用 g++ 或 clang++)：
     打开 终端，输入 编译命令时，添加 -std=c++17 并链接文件系统库。例如：

     g++ -std=c++17 -o my_program my_program.cpp -lstdc++fs
     # 或者对于较新的编译器版本，可能不需要显式链接 -lstdc++fs

   • Windows (使用 Visual Studio)：
     通常无需额外配置，Visual Studio 2017 及以上版本在创建C++17项目时会自动处理。确保项目属性中的“C++语言标准”设置为 ISO C++17 标准 (/std:c++17) 或更高版本。
   • Windows (使用 MinGW g++)：
     与Linux类似，使用 -std=c++17 标志。对于旧版本，可能需要链接 -lstdc++fs。

2. 基础文件与目录操作

掌握基础的文件属性查询和目录创建是后续操作的前提。

1. 检查路径是否存在：使用 fs::exists() 函数。它接受一个 fs::path 对象或能转换为路径的字符串作为参数。

   fs::path filePath = “./data/config.json”;
   if (fs::exists(filePath)) {
       std::cout << “文件存在。” << std::endl;
   } else {
       std::cout << “文件不存在。” << std::endl;
   }

2. 判断是文件还是目录：使用 fs::is_regular_file() 和 fs::is_directory() 函数进行检查。

   if (fs::is_regular_file(filePath)) {
       std::cout << “这是一个普通文件。” << std::endl;
   } else if (fs::is_directory(filePath)) {
       std::cout << “这是一个目录。” << std::endl;
   }

3. 获取文件大小：使用 fs::file_size() 函数获取普通文件的大小（单位为字节）。

   try {
       auto size = fs::file_size(filePath);
       std::cout << “文件大小为: ” << size << “ 字节。” << std::endl;
   } catch (const fs::filesystem_error& e) {
       std::cerr << “获取文件大小失败: ” << e.what() << std::endl;
   }

4. 创建目录：使用 fs::create_directory() 创建单级目录，使用 fs::create_directories() 递归创建多级目录。

   fs::path newDir = “./output/2024/logs”;
   if (fs::create_directories(newDir)) {
       std::cout << “目录创建成功。” << std::endl;
   } else {
       std::cout << “目录已存在或创建失败。” << std::endl;
   }

5. 复制与重命名/移动文件：使用 fs::copy() 复制文件或目录，使用 fs::rename() 重命名或移动文件。

   // 复制文件
   fs::path src = “./source.txt”;
   fs::path dest = “./backup/source_backup.txt”;
   fs::copy(src, dest, fs::copy_options::overwrite_existing); // 覆盖已存在的目标文件
   // 重命名（移动）文件
   fs::path oldName = “./old_name.txt”;
   fs::path newName = “./new_name.txt”;
   fs::rename(oldName, newName);

6. 删除文件或目录：使用 fs::remove() 删除单个文件或空目录，使用 fs::remove_all() 递归删除目录及其所有内容。

   // 删除文件
   fs::remove(“./temp.log”);
   // 递归删除目录（危险操作！）
   fs::remove_all(“./temp_folder”);

3. 目录遍历核心：迭代器

遍历目录是 std::filesystem 最强大的功能之一，它通过迭代器实现。

1. 浅层遍历当前目录：使用 fs::directory_iterator。它会遍历指定目录下的所有直接子项（文件或子目录），但不递归进入子目录。

   fs::path dirPath = “./my_project”;
   for (const auto& entry : fs::directory_iterator(dirPath)) {
       // entry.path() 返回该项的完整路径
       std::cout << entry.path() << std::endl;
       // 也可以检查类型
       if (entry.is_regular_file()) {
           std::cout << ” -> 这是一个文件” << std::endl;
       } else if (entry.is_directory()) {
           std::cout << ” -> 这是一个目录” << std::endl;
       }
   }

2. 递归遍历所有子目录：使用 fs::recursive_directory_iterator。它会深度优先地遍历指定目录下的所有文件和子目录。

   for (const auto& entry : fs::recursive_directory_iterator(dirPath)) {
       std::cout << entry.path().string() << std::endl;
   }

3. 控制递归深度：使用 fs::directory_options::skip_permission_denied 选项可以避免因权限问题中断遍历。构造迭代器时传入选项。

   for (const auto& entry : fs::recursive_directory_iterator(dirPath, fs::directory_options::skip_permission_denied)) {
       // ... 处理 entry
   }

   也可以使用迭代器的 depth() 方法来判断当前递归深度，并手动控制是否进入子目录。

4. 错误处理与路径规范化

健壮的程序必须妥善处理错误，并正确处理跨平台的路径差异。

1. 捕获文件系统异常：大多数 std::filesystem 操作在失败时会抛出 fs::filesystem_error 异常。使用 try-catch 块捕获它。

   try {
       fs::copy(“./non_existent_file.txt”, “./dest.txt”);
   } catch (const fs::filesystem_error& e) {
       // e.code() 返回错误码， e.what() 返回错误信息
       std::cerr << “操作失败: ” << e.what() << std::endl;
   }

   对于一些可能失败但不想抛异常的操作，可以使用带 std::error_code 参数的重载版本。

   std::error_code ec;
   bool success = fs::copy(“./non_existent.txt”, “./dest.txt”, ec);
   if (!success) {
       std::cerr << “复制失败，错误码: ” << ec.message() << std::endl;
   }

2. 路径规范化：不同平台使用不同的路径分隔符（Windows用 \， Linux/macOS用 /）。使用 fs::path 的成员函数可以轻松处理。

   • fs::canonical(p)：返回一个经过解析（去除 . .. 和符号链接）后的绝对路径。要求路径必须存在。
   • fs::absolute(p)：返回绝对路径，但不解析符号链接。路径可以不存在。
   • fs::weakly_canonical(p)：尽可能规范化路径，即使路径部分不存在。
   • path.lexically_normal()：纯词法上的规范化，不访问文件系统。

     fs::path messyPath = “./data/../config/./app.conf”;
     fs::path cleanPath = messyPath.lexically_normal(); // 结果可能是 “config/app.conf”
     fs::path absPath = fs::absolute(messyPath); // 获取当前工作目录下的绝对路径

3. 分解路径：fs::path 提供了丰富的函数来分解路径组件。

   • path.filename()：返回文件名部分（如 “app.conf”）。
   • path.stem()：返回不含扩展名的文件名部分（如 “app”）。
   • path.extension()：返回扩展名部分（如 “.conf”）。
   • path.parent_path()：返回父目录路径。
   • path.root_name()：返回根名称（如Windows的 “C:”）。
   • path.relative_path()：返回相对于根路径的路径。

5. 高级用法与实用技巧

结合基础操作和迭代器，可以实现更复杂的需求。

1. 在遍历时进行过滤：使用 std::copy_if 或 C++20的 std::ranges::filter_view，或者在循环中直接判断。

   // 只遍历扩展名为 .cpp 的文件
   for (const auto& entry : fs::recursive_directory_iterator(dirPath)) {
       if (entry.is_regular_file() && entry.path().extension() == “.cpp”) {
           std::cout << “找到C++源文件: ” << entry.path() << std::endl;
       }
   }

2. 修改遍历时的目录项：迭代器返回的 directory_entry 对象是只读的。要修改文件（如重命名），需要获取其 path() 属性后再操作。

   for (auto& entry : fs::directory_iterator(“./photos”)) {
       if (entry.is_regular_file()) {
           fs::path oldPath = entry.path();
           fs::path newPath = oldPath.parent_path() / (“renamed_” + oldPath.filename().string());
           fs::rename(oldPath, newPath);
       }
   }

3. 创建临时目录：使用 fs::temp_directory_path() 获取系统临时目录，然后结合 create_directories 和唯一名称创建临时工作空间。

   fs::path tempDir = fs::temp_directory_path() / “my_app_temp”;
   fs::create_directories(tempDir);
   // ... 使用临时目录 ...
   // 使用完毕后清理
   fs::remove_all(tempDir);

4. 监控文件变化（轮询模式）：虽然 std::filesystem 不提供事件监控，但可以通过记录最后修改时间来实现简单的轮询监控。

   fs::path watchFile = “./config.ini”;
   auto lastTime = fs::last_write_time(watchFile);
   while (true) {
       // 模拟其他工作
       std::this_thread::sleep_for(std::chrono::seconds(1));
       auto currentTime = fs::last_write_time(watchFile);
       if (currentTime != lastTime) {
           std::cout << “文件已被修改！” << std::endl;
           lastTime = currentTime;
           // 重新加载配置...
       }
   }