WatchService 默认不递归监听子目录，需手动遍历注册；pollEvents() 后必须调用 reset() 否则事件丢失；ENTRY_MODIFY 不保证内容变更；容器/NFS 等场景建议改用轮询或快照比对。
WatchService 为什么监听不到子目录里的改动
默认情况下 WatchService 只监控注册路径的**直接子项**，不会递归监听嵌套目录。比如你注册了 /tmp/project，它能收到该目录下新建文件或重命名事件，但对 /tmp/project/src/main.java 的修改、或 /tmp/project/lib/ 下新增 JAR 文件，统统收不到。
解决办法是手动遍历所有子目录并逐个注册——不是靠“开启递归开关”，而是自己写逻辑走一遍目录树：
- 用
Files.walk()或递归Files.list()扫描目标路径下的所有DirectoryStream - 对每个遍历到的目录调用
path.register(watcher, ENTRY_CREATE, ENTRY_DELETE, ENTRY_MODIFY) - 注意：注册前先检查是否为目录（
Files.isDirectory(path)），避免对文件调用register()抛出IOException - Windows 上单次注册目录数不宜超过几千个，否则可能触发系统句柄限制；Linux/macOS 相对宽松，但仍建议做异常兜底
WatchKey.pollEvents() 返回空列表的常见原因
调用 key.pollEvents() 得到空 List，不代表没事件——大概率是你没调用 key.reset() 导致后续事件被丢弃。
WatchKey 是一次性消费模型：事件触发后进入队列，你必须显式调用 reset() 才能让它继续接收新事件。漏掉这步，后续所有改动都不会再进队列。
- 正确顺序是：
key.pollEvents()→ 处理事件 →if (!key.reset()) break;（返回false表示通道已关闭，需退出循环） - 别在
pollEvents()前加Thread.sleep()等待，这会错过事件窗口；WatchService 是事件驱动，不是轮询机制 - 如果用
key.take()替代pollEvents()，它会阻塞直到有事件，但也一样需要reset()
监听文件内容修改 vs 文件元数据修改的区别
ENTRY_MODIFY 事件不等于“文件内容变了”。在大多数操作系统上，它只表示该路径对应的 inode 元信息发生了变更，比如 mtime 更新、权限变化、硬链接数变动等。而编辑一个文本文件保存时，常见行为是“写新文件 + 原子替换（rename）”，此时你收到的是 ENTRY_CREATE + ENTRY_DELETE，而非 ENTRY_MODIFY。
- 想可靠捕获内容变更，不能只依赖
ENTRY_MODIFY；要组合监听ENTRY_CREATE和ENTRY_DELETE，并在 rename 场景中比对文件名和 size/mtime - 某些编辑器（如 VS Code）启用“保存时创建备份”后，还会多出
.filename.swp类临时文件事件，需过滤 - macOS 上
FSEvents底层更精细，但 Java 的WatchService抽象层屏蔽了这些差异，统一表现为粗粒度事件
WatchService 在容器或网络文件系统中的表现
在 Docker 容器里挂载宿主机目录、或使用 NFS/Samba 共享目录时，WatchService 极易失效或延迟极高——因为 inotify（Linux）、kqueue（macOS）、ReadDirectoryChangesW（Windows）这些底层机制，大多不跨文件系统边界工作。
- Docker for Mac/Windows 使用 gRPC-FUSE 桥接，inotify 事件基本不可用；建议改用轮询（如
File.lastModified()+ 定时扫描） - NFSv3 不支持服务端通知，客户端只能轮询；NFSv4 理论支持回调，但 JDK 并未启用，实际仍不可靠
- 若必须用 WatchService，优先保证路径位于本地 ext4/xfs（Linux）、APFS（macOS）、NTFS（Windows）卷上
真正跨平台又稳定的方案，往往得放弃 WatchService，转而用 java.nio.file.Files.walkFileTree() 配合时间戳快照做差异比对——虽然慢一点，但至少不丢事件。
