先确认遍历范围是当前层还是递归

拿到需求时，我会先问自己一个问题：到底只要遍历当前目录下的直接子项，还是需要进入所有子目录？这个判断决定了该用 std::filesystem::directory_iterator 还是 recursive_directory_iterator。很多新手踩坑是因为把项目写成了递归，后来发现结果里多出了不该出现的深层文件，或者反过来漏掉了子目录里的内容。

容易误判的地方：迭代器角色和符号链接循环

使用 std::filesystem::directory_iterator 可以遍历指定目录下的直接子项。构造迭代器时传入目录路径，然后通过循环获取每个目录项。注意 directory_iterator 默认不遍历子目录，且不会递归处理符号链接指向的目录。在循环中，可以通过 is_regular_file() 或 is_directory() 判断当前项的类型，从而决定后续操作。需要处理的情况是目录不存在或权限不足，此时构造函数会抛出 filesystem_error 异常，建议用 try-catch 块捕获。

如果需要遍历目录及其所有子目录，使用 recursive_directory_iterator。它默认会递归进入子目录，但遇到符号链接时可能重复访问或陷入循环。为防止无限递归，可以检查目录项的 symlink_status().type() 是否为 symlink_file，并跳过或限制深度。另一个风险是遍历过程中目录结构发生变化，可能导致未定义行为，因此不建议在遍历时创建或删除目录项。通过设置 recursion_pending() 可以控制是否继续递归。

我见过一个实际案例：同事用 recursive_directory_iterator 遍历一个挂载了 NFS 的目录，结果遇到符号链接指向了父目录，导致程序陷入无限循环。排查了很久才发现是符号链接的问题。所以如果目录可能包含指向父目录或自身的符号链接，一定要在循环内检查 symlink_status 并主动跳过。

建议的处理顺序：异常处理与错误码二选一

在文件系统遍历中，权限不足或路径无法访问是常见错误。使用 directory_iterator 时，可以传入 std::error_code 参数来避免异常抛出，而是通过错误码判断是否成功。例如：std::error_code ec; for(auto& entry : std::filesystem::directory_iterator(path, ec)) {...}。如果 ec 有值，说明遍历中断，应检查 ec.message() 获取详情。另一种方式是在循环体内单独调用 status() 并检查错误码，但注意 status() 本身也可能失败。

我的习惯是：如果只是在工具脚本里用，直接 try-catch 更省事；如果在长时间运行的服务里，用 error_code 避免异常打断流程更安全。两种方式各有适用场景，建议根据是否在意性能损失来决定。

验证方法：写一个小测试对比输出

写完遍历逻辑后，我通常会先在一个小目录里跑测试，打印每个 entry 的 path() 和类型。先对比一下用 directory_iterator 和 recursive_directory_iterator 的结果是否符合预期。把测试目录的树结构画出来（比如用 tree 命令），然后检查程序输出是否覆盖了所有需要的项目，有没有多出不应存在的深层文件。

如果目录比较大，我会用 std::count_if 统计文件数量，跟系统命令 ls -lR | wc -l 做对比，误差太大就回去查逻辑。需要注意的是，ls 命令也会受符号链接影响，所以最好先确认测试目录里没有循环链接。

回滚和风险：避免在遍历时修改目录结构

一个常见误区是混淆 directory_iterator 与 recursive_directory_iterator 的作用域。前者只遍历当前目录，后者递归遍历，但如果需要限制递归深度，需自行实现计数器。另外，在 range-based for 循环中修改目录（如删除文件）会导致迭代器失效。另一个注意点是路径分隔符：在 Windows 下 std::filesystem::path 使用反斜杠，但在 C++ 字符串字面量中需双重转义，或使用正斜杠提高可移植性。文件名编码问题在不同系统上也可能引发 unexpected behavior。

如果程序正在线上运行，而你需要对目录做遍历，建议先对目录做快照（比如拷贝一份到临时目录），然后遍历快照目录。这样即使原目录在遍历期间被修改，也不会影响结果稳定性。当然，快照本身也会占用磁盘空间，需要确认环境是否允许。

后续维护：注意 C++ 标准版本与编译器支持

std::filesystem 在 C++17 中是正式标准，但不同编译器的初始实现质量参差不齐。比如早期 GCC 7 的 recursive_directory_iterator 在遇到权限拒绝时行为可能不一致，后来才修复。建议在 CI 里测试不同平台下的遍历结果，尤其是 Windows 与 Linux 的路径分隔符差异。另外，如果需要限制递归深度，自己写一个包装函数，用 recursion_pending() 控制递归，不要依赖库默认行为。