先说扫描崩溃。代码用了 std::filesystem::recursive_directory_iterator,没有传 error_code,也没有跳过权限不足的目录。Linux 上某个目录属于别的用户,迭代器在进入时抛出 filesystem_error,异常一路冒到 main() 之外,进程直接退出。日志里只有一句 Permission denied,看不出是哪个目录。
再看替换失败。程序把新版本写到 app.exe.new,再 rename() 到 app.exe。Windows 上只要旧程序还在运行,文件就被占用,改名失败;代码没有检查返回值,继续启动新进程,结果跑的还是旧版本。Linux 上正在执行的二进制可以被替换,行为又不一样,同一段代码在两个平台表现不同。
最后是中文路径。在 Windows 上用 std::string 拼路径,默认按当前系统的窄字符编码解释,不是 UTF-8。终端、日志、配置文件各用一套编码时,路径就会变形。这一篇按「路径怎么表示、怎么查、怎么遍历、怎么改、权限怎么算、怎么原子替换」的顺序讲,所有 C++ 示例都在本机用 g++ 16 编译运行过。
g++ -std=c++20 -Wall -Wextra。文中标注「本机实测」的输出是真实运行结果。涉及 POSIX 权限位、符号链接、fsync 的部分在 Windows 上行为不同,会单独说明。path 不是字符串
std::filesystem::path 是专门表示路径的类型,内部按平台的本地编码存:Windows 上是宽字符,POSIX 上是字节串。它提供拼接、取父目录、取扩展名、比较等操作,比手工拼字符串安全得多。用 / 拼接时,path 会自动按平台规则处理分隔符,不需要自己判断斜杠方向。
#include <filesystem>
#include <iostream>
namespace fs = std::filesystem;
int main() {
fs::path p = "data";
p /= "logs";
p /= "app.log";
std::cout << "path=" << p.string() << "\n";
std::cout << "filename=" << p.filename().string() << "\n";
std::cout << "parent=" << p.parent_path().string() << "\n";
std::cout << "ext=" << p.extension().string() << "\n";
return 0;
}
「跑什么、看到什么算通过」:编译运行后,Windows 上 path 输出 data/logs/app.log,filename 是 app.log,parent 是 data/logs,ext 是 .log。把第三行换成 p /= "app",扩展名应当为空,别用「最后一个点」这种字符串规则去猜。
绝对路径和规范化要分清。absolute() 只是把相对路径接到当前工作目录上,不检查存在性;canonical() 会解析 .. 和符号链接,但目标不存在时抛异常;weakly_canonical() 允许最后一段不存在,适合「准备创建新文件」的场景。发布脚本里判断「这个路径是不是在允许目录下」时,要用 canonical 或 weakly_canonical 之后再比较,不能直接比字符串,否则 ../ 和符号链接都能绕过。
编码是另一个坑。path::string() 在 Windows 上按本地窄编码转换,中文可能丢;要 UTF-8 输出用 u8string(),但它的类型是 std::u8string,C++20 里需要按 char8_t 处理。从 UTF-8 字节构造路径,C++20 可以直接用 fs::path(std::u8string);早期写法 u8path() 在 C++20 已废弃。跨平台代码里,内部统一用 path,只在边界处转换编码。
比较路径也别直接比字符串。两个路径在语义上相同,字面上可能不同:一个是相对路径,一个是绝对路径;一个带 .,一个不带;Windows 上分隔符还可能是反斜杠。要判断「是不是同一个位置」,先规范化再比较;只是「字面是否相同」,用 path 的 == 即可。大小写是否敏感由文件系统决定,代码里不要假设统一小写。
相对路径永远相对于进程的当前工作目录,而不是源文件所在目录。程序被从不同目录启动,同一个相对路径会指向不同位置。需要「以可执行文件为锚点」时,得通过平台 API 取自身路径,再拼出配置或资源目录;std::filesystem 本身不提供「当前可执行文件路径」。
查询:优先用带 error_code 的重载
exists()、is_regular_file()、is_directory()、file_size()、last_write_time() 都有两个版本:一个抛异常,一个接收 std::error_code& 并返回结果。批量扫描、清理、统计这类「允许失败继续」的场景,应该用 error_code 版本,把失败记录下来,而不是让一个坏文件终止整个任务。
fs::path p = "maybe.txt";
std::error_code ec;
bool ok = fs::is_regular_file(p, ec);
if (ec) {
std::cout << "query failed: " << ec.value() << "\n";
} else if (ok) {
auto size = fs::file_size(p, ec);
if (!ec) std::cout << "size=" << size << "\n";
}
注意 file_size() 在出错时返回的是一个极大的无符号值,不能只看返回值判断成功,必须看 ec。类似地,last_write_time() 返回的是文件系统时钟类型,不直接等于 time_t,跨平台换算要小心。
space() 能查到磁盘总量、空闲和可用空间,写入大文件前可以先判断够不够。它查的是路径所在文件系统,不针对单个文件。注意「空闲」和「可用」不是一回事:系统保留的空间对普通用户不可用,按 available 判断更稳。
status() 会跟随符号链接,拿到的是最终目标的类型;symlink_status() 拿到链接本身。清理脚本里如果只想删链接、不想动目标,必须用后者判断。对一个断链调用 status() 会得到 not_found,但链接文件其实还在,这也是两类接口不能混用的原因。
状态查询本身也有开销。每次 status() 都可能触发一次系统调用,递归扫描时对每个条目都查一遍类型、大小、时间,累计起来很可观。很多实现会在 directory_entry 里缓存一部分信息,但缓存是否刷新由实现决定;对实时性要求高的场景,显式调用 refresh() 或重新查询,别假设缓存一定最新。
遍历:异常、权限和符号链接
directory_iterator 遍历一层,recursive_directory_iterator 递归遍历。两者默认遇到错误就抛异常,递归版本还会跟随符号链接,符号链接成环时会一直走下去。生产代码里应当显式传入 directory_options::skip_permission_denied,并且在 increment() 上用 error_code 版本,遇到问题停下或跳过,而不是崩掉。
#include <filesystem>
#include <iostream>
#include <system_error>
namespace fs = std::filesystem;
int main() {
size_t files = 0;
unsigned long long bytes = 0;
std::error_code ec;
for (auto it = fs::recursive_directory_iterator(
"fs_lab", fs::directory_options::skip_permission_denied, ec);
it != fs::recursive_directory_iterator(); it.increment(ec)) {
if (ec) {
std::cout << "iterate stopped: " << ec.value() << "\n";
break;
}
if (it->is_regular_file(ec) && !ec) {
++files;
auto sz = it->file_size(ec);
if (!ec) bytes += sz;
}
}
std::cout << "files=" << files << " bytes=" << bytes << "\n";
}
「跑什么、看到什么算通过」:先建一个 fs_lab/logs/2026 目录,写入一个 12 字节的文件,再运行。本机实测输出是 files=1 bytes=12。把一个子目录的权限改成不可读再跑,带 skip_permission_denied 的版本应当跳过它继续,输出里不出现崩溃;去掉这个选项,应当抛出异常。
遍历顺序是未定义的,别假设「先文件后目录」或「按名字排序」。需要稳定顺序就自己收集再排序。文件数量很大时,迭代器的内存开销很小,但每取一次 status() 都可能触发一次系统调用,递归扫描几十万文件会明显变慢;对性能敏感的场景,可以只取 directory_entry 缓存的信息,避免重复查询。
深度也是可控的。recursive_directory_iterator 提供 depth() 和 pop(),可以在进入某个目录前判断层级,超过限制就跳过。备份、清理这类工具通常应该设一个最大深度,既防止符号链接环,也防止误入特别深的目录。跳过某个目录用 disable_recursion_pending(),它只影响「要不要进入当前目录的子目录」,不影响当前条目本身。
修改:创建、改名、删除
常用的修改操作有 create_directories()、create_directory()、rename()、copy()、remove()、remove_all()、resize_file()。create_directories() 会一路创建缺失的父目录,create_directory() 只建一层;两者在目标已存在时的返回值语义不同,批量建目录时按需选择。
rename 适合替换
同一文件系统内改名是一次元数据操作,快,而且 POSIX 上对已存在的目标是原子的:读的人要么看到旧文件,要么看到新文件。跨文件系统时可能退化为复制加删除。
copy 适合保留原件
copy_file() 加 copy_options 控制是否覆盖、是否递归。它比 rename 慢,但源文件仍在。复制到一半失败会留下不完整的目标,仍然需要临时文件加改名。
remove() 删一个文件或空目录,返回是否删掉;remove_all() 递归删除,返回删除数量,目标不存在时返回 0 而不报错。清理脚本里用 remove_all() 要格外小心,路径算错就是整棵树没了。删除前先确认路径来自可信配置,不要直接拼接用户输入。
复制要看清 copy_options。none 表示目标存在就失败,overwrite_existing 表示覆盖,recursive 让目录复制进入子目录,copy_symlinks 决定是复制链接本身还是复制目标内容。默认值不是「全量复制」,目录不传 recursive 会直接失败。权限、时间戳的保留也有对应选项,但不同平台能保留的元数据不一样,别把它当成精确备份工具。
权限:平台差异很大
permissions() 读写 fs::perms 位掩码,POSIX 上对应读、写、执行三组权限,Windows 上只有「只读」属性真正生效,组和其他人的权限位基本被忽略。查询和修改都有抛异常与 error_code 两个版本。
std::error_code ec;
fs::permissions("fs_lab/logs/app.log",
fs::perms::owner_read | fs::perms::owner_write,
ec);
if (ec) {
std::cout << "chmod failed: " << ec.value() << "\n";
}
auto p = fs::status("fs_lab/logs/app.log", ec).permissions();
std::cout << "owner_write="
<< ((p & fs::perms::owner_write) != fs::perms::none) << "\n";
「跑什么、看到什么算通过」:本机实测输出是 owner_write=1。1 只说明「这个位被设置」,不代表当前进程真的能写;真正判断可写还要看进程身份、ACL、只读挂载。POSIX 上可以用 access() 做一次实际检查,但检查和之后的使用之间仍有竞争窗口。
权限错误码常见的是 permission_denied,对应 std::errc::permission_denied。把它和「文件不存在」「路径是目录」区分开,日志里才能给出正确提示。fs::status() 对不存在的路径返回 file_type::not_found,不会抛异常;fs::symlink_status() 查的是链接本身,不跟随目标。
permissions() 模拟 Linux 的 0644/0755 会失败或只改到只读位。需要精确权限时,按平台分别实现,别指望一套位掩码通吃。原子替换:临时文件加 rename
配置、索引、导出文件都适合「先写临时文件,再改名替换」。顺序是:在目标同目录创建临时文件,写完数据,flush() 并关闭流,然后 rename() 覆盖目标。改名之前必须关闭,Windows 上目标或临时文件还被句柄占用时,rename 会直接失败。
#include <filesystem>
#include <fstream>
#include <iostream>
#include <system_error>
namespace fs = std::filesystem;
int main() {
fs::path target = "fs_lab/logs/app.log";
fs::path tmp = target;
tmp += ".tmp";
{
std::ofstream out(tmp, std::ios::binary);
out << "line1\nline2\n";
}
std::error_code ec;
fs::rename(tmp, target, ec);
std::cout << "rename ec=" << ec.value() << "\n";
}
「跑什么、看到什么算通过」:本机实测输出 rename ec=0。先打开目标文件不关,再执行 rename,Windows 上应当得到非零错误码;Linux 上通常仍能成功,因为正在打开的文件可以被替换。两个平台都要实测,不能拿一边的结论套另一边。
rename 的原子性只覆盖「目录项替换」这一步。数据是否真正落盘,取决于文件系统和是否调用了 fsync;C++ 标准库没有直接暴露 fsync,需要平台 API。突然断电时,可能出现「目录里是新文件名,内容还没写完」的情况。对持久性要求高的场景,写完临时文件后先 fsync,再 rename,再 fsync 目录。
平台 API 大致是这样:POSIX 上对流句柄调用 fsync(),对目录也调用一次,让目录项变更落盘;Windows 上对流句柄调用 FlushFileBuffers(),替换可以用 MoveFileEx() 加 MOVEFILE_REPLACE_EXISTING。标准库的 rename 内部也走类似机制,但它不承诺「关闭时一定刷盘」,所以持久性要求高时,平台调用不能省。
还要处理「目标被占用」。Windows 上替换正在运行的可执行文件通常失败,发布程序要么先把旧进程停掉,要么使用系统提供的延迟替换机制。Linux 上正在运行的文件可以被替换,进程继续持有旧 inode,直到退出;这意味着一台机器上可能同时存在「旧进程跑旧文件、新进程跑新文件」,版本判断不能只看文件名。
大文件不要整读
std::filesystem 只负责元数据和目录操作,不负责读写内容。读写仍然用 ifstream/ofstream 或平台 API,按块处理。一个常见错误是用 seekg(0, end) 拿到大小,一次性 read() 进 std::string,文件一大就 bad_alloc。正确做法是固定缓冲区循环读,边读边处理。
复制大文件可以用 copy_file(),它由实现决定内部块大小,通常比手写循环省事;但需要进度、限速、校验时还是得自己读。无论哪种,目标文件都应当先写临时路径,成功后再改名,避免失败时留下半个文件被当成完整数据。
文件大小、修改时间、权限这些元数据在不同文件系统上精度不同。网络文件系统的时间戳可能只到秒,容器挂载的卷可能不支持下某些权限位。用元数据做「是否变化」的判断时,最好同时看大小和时间,必要时加内容校验。
块大小不是越大越好。一次读几 MB 能减少系统调用,但会占内存、拉高延迟;一次读几十字节又会让调用次数暴涨。顺序读写常用的块在几十 KB 到几 MB 之间,具体要看磁盘、文件系统和访问模式。写完记得检查流状态,badbit 或 failbit 置位时数据可能只写了一半。
现象、真实原因、第一步查什么
| 你看到的现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 递归扫描到某个目录直接崩溃 | 迭代器抛 filesystem_error,没有 error_code 重载或没有跳过权限 | 是否传了 skip_permission_denied 和 ec |
| rename 报「文件被占用」 | 目标仍被进程或句柄打开,Windows 上尤其严格 | 是否先关闭了 ofstream;谁还持有目标文件 |
| 中文路径显示成问号 | string() 按本地窄编码转换,源不是 UTF-8 | 用 u8string() 输出,确认输入字节编码 |
明明文件存在,exists() 返回 false | 相对路径按当前工作目录算,或权限不足 | 打印 absolute()/canonical() 和 ec |
| 遍历顺序每次不同 | 目录迭代顺序未定义 | 是否需要自己排序;不要依赖实现顺序 |
| 符号链接目录导致无限递归 | 递归迭代器跟随链接,形成环 | 改用不跟随链接的选项,或记录已访问的规范路径 |
file_size() 返回一个巨大数字 | 出错时返回无符号最大值,只看了返回值 | 检查 error_code,不要用返回值判断成功 |
| 替换后文件内容不完整 | 没关闭流就 rename,或跨文件系统 rename 退化 | 确认临时文件与目标同目录,改名在关闭之后 |
边界与代价
- 异常版和 error_code 版不能混着用。一个函数抛异常,调用方却只看返回值,错误就被吞了。项目里约定清楚:批处理用
ec,关键路径可以抛。 - 路径规范化有成本。
canonical()要访问文件系统,在热路径里反复调用会变慢;可以缓存结果,但文件系统变化后缓存会旧。 - 原子替换不等于持久化。rename 只保证目录项切换,掉电后的数据完整性要靠 fsync 和文件系统。
- 权限模型不可移植。POSIX 的位掩码和 Windows 的属性/ACL 不是一回事,跨平台代码要分别处理。
- 递归删除很危险。
remove_all()不会问你「确定吗」,路径来自配置或用户输入时必须先校验,最好限制在允许的根目录内。
当天能自己验证的练习
- 编译本文的遍历示例,分别在有权限和无权限的子目录下运行,对比带与不带
skip_permission_denied的结果。 - 写一个「临时文件加 rename」的配置替换函数,在 Windows 上故意不关闭 ofstream,观察错误码;关闭后再跑一次。
- 用
u8string()输出一个含中文的路径,再把同一个路径用string()输出,比较两者在终端里的差异。 - 用
space()查询某个磁盘的容量、空闲和可用空间,思考为什么「空闲」大于「可用」。 - 构造一个符号链接环,用默认选项遍历,观察是否无限递归;再加上不跟随链接的选项重跑。
小结
三句话:内部统一用 fs::path,只在边界处理编码;批量操作优先用带 error_code 的重载,遍历时跳过无权限目录;替换文件一律「同目录临时文件、关闭、rename」,并清楚它只保证目录项原子。文件系统是所有后续 IO 的地基,地基不稳,上层再花哨也没用。
文件能可靠落盘之后,下一步是把数据通过网络送出去。下一篇讲 C++ 的网络编程:socket 的基本调用、阻塞与非阻塞的差别、select/epoll 怎么等多个连接,以及为什么 recv() 一次读到的不是一条完整消息。