在C++项目里处理批量文件任务时，经常需要把某个文件夹下面的所有文件找出来，包括层层嵌套的子目录中的内容。早期我们依赖系统相关的API，例如Windows的FindFirstFile或者Linux的opendir，不仅代码碎片化，而且移植成本很高。从C++17开始，标准库提供了filesystem组件，让目录遍历和路径处理变成跨平台的统一操作。
一、C++17 filesystem基础与环境
filesystem定义在头文件<filesystem>中，标准命名空间为std::filesystem。主流编译器如GCC 8、Clang 7、MSVC 2017以上都已完成支持。若使用较旧构建系统，可能需手动链接stdc++fs库。路径类型统一为path，它可以接受字符串并自动适配平台分隔符。
理解path对象是后续操作的核心。它不只是字符串包装，内部会记录首选分隔符，并提供各类方法如extension()、filename()、parent_path()。相比直接用std::string拼路径，path能减少因为“/”和“”混用导致的bug。
二、单层目录遍历：directory_iterator
如果只需要查看某个目录直接包含的文件和文件夹，不进入子目录，可以使用directory_iterator。它在构造时传入一个path，然后通过循环读取每一个directory_entry。每个entry能拿到路径、文件大小、是否为目录等基本信息。
下面示例展示如何列出指定目录下的所有条目，并区分文件与文件夹：
#include <iostream>
#include <filesystem>
namespace fs = std::filesystem;
int main() {
fs::path dir = "./test_folder";
if (!fs::exists(dir)) {
std::cout << "目录不存在" << std::endl;
return 1;
}
for (const auto& entry : fs::directory_iterator(dir)) {
if (entry.is_directory()) {
std::cout << "[文件夹] " << entry.path().string() << std::endl;
} else {
std::cout << "[文件] " << entry.path().string() << std::endl;
}
}
return 0;
}
上述代码利用范围for循环简化迭代，entry.path()返回完整的path对象。要注意directory_iterator不会递归，遇到子目录时只会把它当成一个目录项列出，不会展开里面的内容。
这种方式的优点是简单、安全，不会因目录过深导致栈溢出。缺点是必须自己写递归逻辑才能处理嵌套结构。对于只需要单层资源的场景，例如读取配置目录下的全部配置文件，它是最轻量的选择。
三、递归遍历所有文件：recursive_directory_iterator
当需要“遍历文件夹下的所有文件”这一完整需求时，recursive_directory_iterator是首选。它在内部维护栈结构，自动进入子目录，按深度优先顺序产出每个文件或目录项。
以下例子递归打印某个根目录下的全部普通文件路径：
#include <iostream>
#include <filesystem>
namespace fs = std::filesystem;
int main() {
fs::path root = "./project";
try {
for (const auto& entry : fs::recursive_directory_iterator(root)) {
if (entry.is_regular_file()) {
std::cout << entry.path().string() << std::endl;
}
}
} catch (const fs::filesystem_error& e) {
std::cerr << "遍历出错: " << e.what() << std::endl;
}
return 0;
}
代码中用try-catch包裹迭代过程，因为某些子目录可能没有访问权限，或者遇到断开的符号链接，都会抛出filesystem_error。如果不捕获，程序会直接终止。is_regular_file()用于过滤掉目录和特殊文件，只保留普通文件。
如果希望跳过某些目录，可以调用迭代器的disable_recursion_pending()，在循环内判断路径名称后禁止深入。例如忽略名为node_modules的目录能显著提升前端项目扫描效率。这种控制在批量处理日志、资源打包时非常实用。
四、路径操作常见方法
路径拼接是遍历中高频操作。不要用字符串相加来构造新路径，而应使用path的除法运算符，它能正确处理分隔符。例如父路径 / 文件名就能生成合法路径。
#include <filesystem>
#include <iostream>
namespace fs = std::filesystem;
int main() {
fs::path base = "/data";
fs::path file = base / "logs" / "app.log";
std::cout << file.string() << std::endl;
std::cout << "扩展名: " << file.extension().string() << std::endl;
std::cout << "文件名: " << file.filename().string() << std::endl;
}
除了拼接，path还提供relative_path()、stem()等方便的方法。stem()获取不带扩展名的文件名，适合批量重命名；relative_path()在已知根时提取相对路径，便于展示。组合这些API能让遍历后的处理逻辑清晰易读。
在Windows平台，path会自动把“/”转成“”，但在调用第三方库需要特定分隔符时，可使用make_preferred()强制统一。了解这些细节，可以避免路径在跨平台发布时失效。
五、性能与异常处理建议
大量小文件遍历时，频繁调用status()会有系统调用开销。directory_entry已缓存部分文件属性，优先使用entry.is_file()而非fs::is_regular_file(entry.path())，可减少重复查询。对百万级文件场景，这一差别非常明显。
遍历过程中还应考虑符号链接循环。recursive_directory_iterator默认不跟随符号链接目录，因此不会死循环，但如果用递归函数自己实现，必须记录已访问inode或路径以防无限递归。此外，权限拒绝不应中断整体任务，捕获异常后继续下一个条目是更稳健的做法。
| 遍历方式 | 是否递归 | 适用场景 |
|---|---|---|
| directory_iterator | 否 | 单层配置读取、目录监控 |
| recursive_directory_iterator | 是 | 全量文件搜索、批量处理 |
综合来看，C++17 filesystem让目录遍历从系统相关代码变成标准、简洁的逻辑。掌握迭代器差异与path操作，基本能覆盖日常所有文件枚举需求。
C++17_filesystem目录遍历路径操作修改时间：2026-08-09 03:12:31