readdirectorychangesw 必须用异步 i/o，因同步调用会阻塞线程且无法预知事件数量，易导致缓冲区截断或浪费；异步方式配合有效 overlapped 和正确解析链表才是 windows 官方推荐且唯一稳定方案。
ReadDirectoryChangesW 为什么必须用异步 I/O
同步调用 ReadDirectoryChangesW 会直接阻塞线程，且一旦目录中发生大量变更（比如解压、Git 切分支），单次调用可能返回数百个 FILE_NOTIFY_INFORMATION 记录，而你无法预知要读多少字节 —— 缓冲区太小会截断，太大又浪费。异步（OVERLAPPED + INFINITE 等待）才是 Windows 官方推荐方式，也是唯一能稳定捕获全部事件的路径。
关键点：
- 必须传入有效的
OVERLAPPED结构体，且其hEvent字段需由CreateEvent创建（手动重置模式） -
lpBuffer建议至少 8KB，太小容易触发ERROR_NOTIFY_ENUM_DIR错误并丢失后续事件 - 每次调用前要重置
OVERLAPPED的Internal和InternalHigh字段（可用ZeroMemory） - 不能在 GUI 线程或消息循环中长期等待，应单独起监控线程
如何正确解析 FILE_NOTIFY_INFORMATION 链表
ReadDirectoryChangesW 返回的不是单个结构，而是一个变长、首尾相连的链表：每个节点以 NextEntryOffset 指向下一项，末尾为 0。手动遍历稍有不慎就会越界或死循环。
安全解析要点：
立即学习“C++免费学习笔记（深入）”；
- 必须用
reinterpret_cast<file_notify_information>(buffer)</file_notify_information>起始，而非直接取址 - 每轮检查
next->NextEntryOffset != 0，且确保next = reinterpret_cast<file_notify_information>(reinterpret_cast<char>(cur) + cur->NextEntryOffset)</char></file_notify_information>不超出缓冲区边界 -
FileNameLength是字节数（不是字符数），需除以sizeof(WCHAR)才得真实字符长度 - 文件名是宽字符串，未以
L'\0'结尾，必须用std::wstring(filename, filename + len)构造
常见崩溃和静默失败原因
多数 C++ 监控程序跑几分钟就崩或漏事件，往往栽在这几处：
- 重复使用同一个
OVERLAPPED实例发起多次异步请求 —— 必须为每次调用分配独立OVERLAPPED或显式重置其内核状态（ResetEvent+ 清零字段） - 在回调或等待返回后，未调用
GetOverlappedResult就直接解析 buffer —— 此时 buffer 内容无效，InternalHigh也未更新 - 监听目录句柄被意外关闭（如
CloseHandle被误调），后续ReadDirectoryChangesW调用返回FALSE且GetLastError()为ERROR_INVALID_HANDLE - 未处理
FILE_ACTION_RENAMED_OLD_NAME和FILE_ACTION_RENAMED_NEW_NAME成对出现的情况，导致把重命名识别成“删除+新建”
最小可运行监控线程示例
以下代码片段可直接嵌入项目，仅依赖 WinAPI，无第三方库：
#include <windows.h>
#include <vector>
#include <string>
#include <iostream><p>DWORD WINAPI MonitorThread(LPVOID lpParam) {
const std::wstring& path = <em>static_cast<std::wstring</em>>(lpParam);
HANDLE hDir = CreateFileW(path.c_str(), FILE_LIST_DIRECTORY,
FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE,
nullptr, OPEN_EXISTING, FILE_FLAG_BACKUP_SEMANTICS | FILE_FLAG_OVERLAPPED, nullptr);
if (hDir == INVALID_HANDLE_VALUE) return 1;</p><pre class='brush:php;toolbar:false;'>HANDLE hEvent = CreateEvent(nullptr, TRUE, FALSE, nullptr);
OVERLAPPED overlapped = {0};
overlapped.hEvent = hEvent;
std::vector<BYTE> buffer(8192);
BOOL bSuccess = ReadDirectoryChangesW(hDir, buffer.data(), (DWORD)buffer.size(),
TRUE, FILE_NOTIFY_CHANGE_FILE_NAME | FILE_NOTIFY_CHANGE_LAST_WRITE,
nullptr, &overlapped, nullptr);
while (bSuccess || GetLastError() == ERROR_IO_PENDING) {
WaitForSingleObject(hEvent, INFINITE);
DWORD dwBytes;
if (GetOverlappedResult(hDir, &overlapped, &dwBytes, FALSE)) {
auto* pNotify = reinterpret_cast<FILE_NOTIFY_INFORMATION*>(buffer.data());
do {
std::wstring name(pNotify->FileName, pNotify->FileNameLength / sizeof(WCHAR));
switch (pNotify->Action) {
case FILE_ACTION_ADDED: std::wcout << L"[ADD] " << name << L"\n"; break;
case FILE_ACTION_MODIFIED: std::wcout << L"[MOD] " << name << L"\n"; break;
case FILE_ACTION_REMOVED: std::wcout << L"[DEL] " << name << L"\n"; break;
}
if (pNotify->NextEntryOffset == 0) break;
pNotify = reinterpret_cast<FILE_NOTIFY_INFORMATION*>(
reinterpret_cast<char*>(pNotify) + pNotify->NextEntryOffset);
} while (true);
}
// 重置并发起下一次监听
ResetEvent(hEvent);
ZeroMemory(&overlapped, sizeof(overlapped));
overlapped.hEvent = hEvent;
bSuccess = ReadDirectoryChangesW(hDir, buffer.data(), (DWORD)buffer.size(),
TRUE, FILE_NOTIFY_CHANGE_FILE_NAME | FILE_NOTIFY_CHANGE_LAST_WRITE,
nullptr, &overlapped, nullptr);
}
CloseHandle(hEvent);
CloseHandle(hDir);
return 0;}
注意：FILE_NOTIFY_CHANGE_LAST_WRITE 会高频触发（尤其是文本编辑器保存时），若只需捕获增删改名，建议只留 FILE_NOTIFY_CHANGE_FILE_NAME；实际部署时还要加异常路径判断（如符号链接、权限不足）和 buffer 动态扩容逻辑。
