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(buffer) 起始，而非直接取址
• 每轮检查 next->NextEntryOffset != 0，且确保 next = reinterpret_cast(reinterpret_cast(cur) + cur->NextEntryOffset) 不超出缓冲区边界
• 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 
#include 
#include 
#include 
DWORD WINAPI MonitorThread(LPVOID lpParam) {
const std::wstring& path = static_cast>(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;
HANDLE hEvent = CreateEvent(nullptr, TRUE, FALSE, nullptr);
OVERLAPPED overlapped = {0};
overlapped.hEvent = hEvent;

std::vector 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(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(
                reinterpret_cast(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 动态扩容逻辑。