Java NIO WatchService 收不到子目录变化怎么办

只给根目录调用一次 register()，Java NIO WatchService 不会自动替你监听整棵目录树。已有子目录需要在启动时逐个注册；运行中又创建了子目录，还要在父目录收到 ENTRY_CREATE 后补一次注册。否则你看到的现象就是“根目录有事件，子目录没反应”。

一、先明确 WatchService 只监听已注册目录

Path.register(watcher, ...) 的注册对象是当前这个目录，不是它下面的所有目录。事件的 context() 也是相对于产生事件的已注册目录的路径，所以消费事件时必须先用 watchedDir.resolve(context) 拼出真实子路径。

下面这张图把监听服务、WatchKey、目录和事件类型放在同一张静态关系图里。它是结构示意，不是本机运行截图。

二、启动时递归注册已有目录

先创建一个 WatchService，再用 Files.walkFileTree 遍历现有目录。在每个 preVisitDirectory 中注册三类目录事件，并把返回的 WatchKey 与目录存入 Map。这样即使文件位于两层、三层子目录，也能找到对应的监听上下文。

private final Map keys = new HashMap();

private void registerDirectory(Path dir) throws IOException {
    // 每个目录都要单独注册，WatchService 不会自动递归。
    WatchKey key = dir.register(watcher,
            StandardWatchEventKinds.ENTRY_CREATE,
            StandardWatchEventKinds.ENTRY_DELETE,
            StandardWatchEventKinds.ENTRY_MODIFY);
    keys.put(key, dir);
}

private void registerTree(Path root) throws IOException {
    // 启动时覆盖已经存在的目录，避免只监听根目录。
    Files.walkFileTree(root, new SimpleFileVisitor() {
        @Override
        public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs)
                throws IOException {
            registerDirectory(dir);
            return FileVisitResult.CONTINUE;
        }
    });
}

这里的关键不是“递归调用 register”，而是让每个实际目录都有自己的 WatchKey。创建服务时可用 FileSystems.getDefault().newWatchService()，关闭时配合 try-with-resources 或显式调用 close() 释放资源。

三、新建子目录后要补注册

启动时不存在的目录不可能被前面的遍历注册。因此父目录收到 ENTRY_CREATE 后，要把事件的相对 context 解析到父目录下，再判断它是否为目录。如果是，就注册它；若该目录可能已带有更深层结构，则继续调用 registerTree(child)。

private void handleEvent(WatchKey key, WatchEvent> event) throws IOException {
    Path watchedDir = keys.get(key);
    if (watchedDir == null) {
        // 找不到目录时不猜路径，避免把事件归到错误的 WatchKey。
        return;
    }

    if (event.kind() == StandardWatchEventKinds.OVERFLOW) {
        // OVERFLOW 表示可能丢事件，真实状态应通过重新扫描目录确认。
        rescan(watchedDir);
        return;
    }

    @SuppressWarnings("unchecked")
    WatchEvent pathEvent = (WatchEvent) event;
    Path child = watchedDir.resolve(pathEvent.context());
    if (event.kind() == StandardWatchEventKinds.ENTRY_CREATE
            && Files.isDirectory(child, LinkOption.NOFOLLOW_LINKS)) {
        // 新目录必须马上接入监听；目录内已有层级也一并登记。
        registerTree(child);
    }
    consume(child, event.kind(), event.count());
}

Files.isDirectory 只是判断当前可见状态，创建事件与实际写入之间可能存在竞态；生产代码应捕获 NoSuchFileException 和 IOException，把“目录已被删除”与“权限或文件系统失败”分开记录。

四、正确消费 WatchKey 并处理边界

监听循环通常从 watcher.take() 取出 WatchKey，再遍历 pollEvents()。处理完全部事件后调用 reset()，返回 false 说明该 key 已失效，应该从 Map 删除并停止依赖它。

for (;;) {
    WatchKey key;
    try {
        // take 会等待下一个已被唤醒的目录注册。
        key = watcher.take();
    } catch (InterruptedException ex) {
        // 响应线程停止信号，恢复中断标记后退出监听线程。
        Thread.currentThread().interrupt();
        break;
    }

    for (WatchEvent> event : key.pollEvents()) {
        try {
            handleEvent(key, event);
        } catch (IOException ex) {
            // 单个目录失败不应吞掉异常，交给上层记录并决定是否重扫。
            logFailure(ex);
        }
    }
    if (!key.reset()) {
        // 目录被删除或文件系统不可访问时，移除失效映射。
        keys.remove(key);
    }
}

不要把一次 ENTRY_MODIFY 当成“文件已经完全写完”的证明，官方 API 明确没有这个保证。文件写入方仍在工作时，消费方应采用临时文件改名、稳定性检查或重试策略。对高频目录还要设计 OVERFLOW 后的重扫，确保最终状态来自目录扫描，而不是只依赖可能丢失的事件。

常见问题

只注册根目录，为什么能收到根目录下的新文件？

因为新文件是根目录的直接条目；子目录是另一个目录对象，里面的变化不会自动冒泡成根目录的文件事件。

新建目录后立刻写入文件，仍可能漏掉吗？

可能。创建目录和写入文件之间存在竞态，动态注册应尽快执行，并在必要时对新目录做一次扫描或延迟重扫。

WatchService 能保证所有事件不丢吗？

不能。事件积压时可能收到 OVERFLOW；它是重新检查目录状态的信号，不能当成普通路径事件。