Java WatchService是NIO.2提供的轻量级文件系统事件监听机制，依赖操作系统原生通知（如inotify），需注册目录、手动重置WatchKey、注意事件丢失与跨文件系统限制，推荐配合第三方封装使用。
Java 的 WatchService 是 NIO.2 提供的轻量级文件系统事件监听机制，适合监控目录内文件的创建、修改、删除等变更。它底层依赖操作系统原生的文件通知（如 Linux 的 inotify、Windows 的 ReadDirectoryChangesW），效率高、资源占用低，但使用时需注意其异步性、一次性事件和路径注册限制等特性。
注册监控路径并监听事件
WatchService 本身不主动轮询，需要先获取服务实例，再为**目录**（不能是文件）注册感兴趣的事件类型：
- 调用
FileSystems.getDefault().newWatchService()创建服务 - 用
Path.register(WatchService, WatchEvent.Kind...)注册目标目录，支持StandardWatchEventKinds.ENTRY_CREATE、ENTRY_MODIFY、ENTRY_DELETE - 每个注册只对当前目录生效，子目录不会自动递归监控，需手动遍历注册（或配合 Files.walkFileTree 实现）
正确处理 WatchKey 的循环轮询
事件到达后会触发 WatchKey 就绪，必须显式调用 key.pollEvents() 获取事件列表，并在处理完后调用 key.reset() 重置状态，否则该 key 后续不再接收新事件：
- 使用
watchService.take()阻塞等待事件（推荐），或poll()非阻塞方式 - 每个
WatchEvent包含事件类型、发生路径（相对于注册目录）、上下文信息 - 忘记 reset() 是常见 bug —— 导致监听“失灵”
- 示例：若监听
/tmp，事件路径可能是"log.txt"（不是绝对路径）
处理常见边界情况
WatchService 行为受系统和 JVM 限制，需主动应对：
立即学习“Java免费学习笔记（深入）”；
- 事件可能丢失：高频操作（如解压大量文件）可能导致合并或丢弃，建议结合时间戳校验或业务层兜底
- 跨文件系统移动失效：mv 到未注册目录或不同磁盘时，原监控无响应
- 软链接与符号链接默认不跟踪：注册时需确保路径是真实目录，避免指向失效
-
异常需捕获并恢复：I/O 异常或 key 失效（
!key.isValid()）时应重新注册或记录告警
简化开发可考虑第三方封装
原生 API 较底层，易出错。如需递归监控、去抖动、事件过滤或 Spring 集成，可选用：
-
Apache Commons IO 的
FileAlterationObserver（基于轮询，兼容性好但非实时） - Spring Boot 2.7+ 的
@EventListener+FileSystemWatcher（自动管理生命周期） - WatchService 封装库如
io.methvin.watchservice（支持 macOS/Linux/Windows，修复 JDK 原生缺陷）
