ReadDirectoryChangesW监控失败主因是目录句柄未用FILE_FLAG_BACKUP_SEMANTICS打开或缓冲区不足8KB；须异步调用、链式解析FILE_NOTIFY_INFORMATION，且路径末尾不可带反斜杠。
Windows下用ReadDirectoryChangesW监控目录必须开句柄并保持线程阻塞
直接调用ReadDirectoryChangesW失败，十有八九是因为没正确打开目录句柄或没分配足够大的缓冲区。它不返回事件列表，而是把变化数据异步写进你提供的内存块里，所以必须配对使用CreateFile（带FILE_FLAG_BACKUP_SEMANTICS）和持续等待的I/O模型。
-
CreateFile路径末尾不能带反斜杠，否则会失败并返回ERROR_PATH_NOT_FOUND - 缓冲区大小建议至少 8KB（
8192），小了容易截断导致解析出错；实际事件结构FILE_NOTIFY_INFORMATION是变长的，必须按NextEntryOffset链式遍历 - 别用同步模式（
NULL作为lpOverlapped），否则会卡死——即使只监一个目录，也得用OVERLAPPED+GetQueuedCompletionStatus或WaitForSingleObject配合 - 常见误判：
FILE_ACTION_MODIFIED可能对应内容改、属性改、时间戳更新，无法区分；重命名操作会触发FILE_ACTION_RENAMED_OLD_NAME和FILE_ACTION_RENAMED_NEW_NAME两条记录
Linux下inotify添加监控项后要手动读取事件流，且read()可能返回不完整结构
inotify_add_watch只是注册监听，真正事件要靠反复read()从inotify_fd里捞。返回的数据不是标准结构数组，而是一段连续二进制流，每个struct inotify_event紧挨着下一个，len字段只表示其后name长度（不含\0），整个事件总长需手动计算。
- 每次
read()建议用至少 4KB 缓冲区（sizeof(struct inotify_event) + NAME_MAX + 1），小于这个值可能一次读不完一个完整事件 -
IN_MOVED_TO和IN_MOVED_FROM共用同一个cookie值，配对识别移动/重命名；但若中间穿插了其他事件，cookie可能被覆盖，不能只靠它做严格匹配 - 监控子目录需逐层
inotify_add_watch，inotify本身不递归；删除被监控目录时，对应watch自动失效，但fd仍有效，继续read()会返回0（EOF） - 注意
IN_IGNORED事件：当watch被移除（如inotify_rm_watch）或所在目录被删除时触发，此时该watch已不可用，不应再尝试解析后续事件
跨平台封装时别试图统一事件类型枚举，优先保证路径和动作语义对齐
Windows的FILE_ACTION_*和Linux的IN_*没有一一映射关系，硬凑枚举会导致逻辑漏洞。比如IN_ACCESS（文件被读）在Windows无对应项；FILE_ACTION_ADDED在Linux可能对应IN_CREATE或IN_MOVED_TO，取决于是否由移动引发。
- 对外暴露的事件结构至少包含：
path（相对监控根路径）、action（抽象为created/deleted/modified/renamed四级）、is_directory - Windows下
ReadDirectoryChangesW返回的FileName是UTF-16，需转UTF-8；Linux下inotify_event.name是原始字节，一般为UTF-8，但不保证，应原样透传或由上层指定编码 - 避免在回调里做耗时操作：两个平台的事件通知都是内核级投递，处理慢会导致事件积压（Windows缓冲区满后丢事件，Linux
inotify队列满后产生IN_Q_OVERFLOW）
调试时先确认基础权限和路径有效性，再查事件漏报或重复
漏报比崩溃更难定位。Windows下检查目录是否有FILE_LIST_DIRECTORY权限，Linux下确认进程对路径有执行（x）权限（否则inotify_add_watch失败返回-1且errno=EPERM）。重复事件常见于编辑器保存策略：有些工具先写临时文件再rename，看起来像两次created；Git切换分支也可能批量触发modified。
- 用
Process Monitor（Win）或strace -e trace=inotify_add_watch,inotify_rm_watch,read（Linux）验证系统调用是否如期发生 - 测试时禁用杀毒软件/备份工具——它们常大量访问文件，干扰监控逻辑
- 监控网络路径（SMB/NFS）在Windows上可能完全不触发，Linux下
inotify对远程挂载点基本无效，得换fanotify或轮询
实际跑起来之后，最麻烦的往往不是API调用本身，而是事件语义的模糊性与边界场景：编辑器保存、IDE索引、版本工具写锁文件、甚至系统休眠唤醒后的状态恢复，都可能让“文件被修改”这件事变得难以归因。留好日志开关，让每条原始事件可追溯，比追求一次写对更重要。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
