Go fsnotify Add 为什么不会自动递归监听目录

我第一次用 fsnotify 监听配置目录时，直觉是把根目录传给 watcher.Add，然后等整个目录树的变化都从 Events 通道出来。结果只有根目录下的文件能触发通知，深层子目录却像不存在一样。原因很明确：Add(path) 的语义是登记一个具体路径，不是递归订阅它下面的所有目录。

官方依据：https://github.com/fsnotify/fsnotify　https://pkg.go.dev/github.com/fsnotify/fsnotify

因此，目录树监听要拆成两件事：启动时遍历已经存在的目录并逐个调用 Add；运行中发现新的目录时，再把这个目录补进 watcher。只做前半段，启动后创建的子目录仍然不会被监听。

为什么 Add 不会自动递归

Watcher.Add(path) 接收的是一个路径登记请求。根目录、根目录下的 configs，以及 configs/dev 是三个不同的目录节点；把第一个节点交给 Add，并不会替调用方把后两个节点逐一登记。fsnotify 官方 FAQ 也明确要求：想监听哪些子目录，就分别添加哪些子目录。

这不是 Go 代码漏写了一个递归参数，而是库和底层文件通知后端的职责边界。不同平台使用的通知机制不同，watch 数量、文件描述符和目录事件语义也不完全相同，所以库把“哪些路径要订阅”留给应用层决定。

先把已有目录逐个加入 watcher

我通常把初始化拆成一个小函数：用 filepath.WalkDir 扫描目录树，遇到目录才调用 Add，遇到普通文件则跳过。这样既能覆盖启动时已经存在的层级，也不会为每个文件额外创建 watch。

package main

import (
    "fmt"
    "io/fs"
    "path/filepath"

    "github.com/fsnotify/fsnotify"
)

// addExistingDirs 只登记目录节点，避免把普通文件当成递归监听入口。
func addExistingDirs(w *fsnotify.Watcher, root string) error {
    return filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
        // 目录不可读时保留原始错误，让调用方决定是否终止初始化。
        if walkErr != nil {
            return walkErr
        }
        if !entry.IsDir() {
            return nil
        }
        // 每个目录都要单独 Add；父目录不会替子目录自动订阅。
        if err := w.Add(path); err != nil {
            return fmt.Errorf("add watch %s: %w", path, err)
        }
        return nil
    })
}

这段代码的关键不是“递归”三个字，而是把目录树展开成多个明确的 Add 调用。若根目录不存在、没有权限，或平台资源不足，初始化函数会返回错误；生产代码可以按业务需要记录失败路径，但不要假装整个目录树已经覆盖。

运行中新增的目录也要补登记

只在启动时用 WalkDir 仍有一个缺口：程序启动后，用户可能创建 configs/new。此时根目录已经在监听范围内，事件里通常可以看到这个新目录，但它不会自动成为新的 watch。收到 Create 且目标是目录后，应立即调用 Add(event.Name)。

func consume(w *fsnotify.Watcher, root string) error {
    for {
        select {
        case event, ok := 

上面的片段只展示事件处理边界，完整程序还需要导入 os、strings，并在退出时调用 w.Close()。如果创建目录后马上写文件，应用还要考虑事件到达顺序和目录是否已经可 Stat；必要时可以把补登记动作放进带去重的队列。

我会保留的三个检查点

还要留意平台差异：官方文档提示 Linux 的 inotify 有 watch 和 instance 上限，macOS/BSD 的 kqueue 会消耗文件描述符。目录很多时，递归监听并不是“多写一个循环”这么简单，而是要配合过滤、去重、关闭和资源预算。

相关问题

只监听一个文件可以吗？

可以调用 Add 登记文件，但官方文档不建议把它作为编辑器场景的首选，因为很多程序会通过临时文件替换原文件。更稳妥的做法通常是监听父目录，再用 Event.Name 过滤目标文件。

新建目录后为什么仍然漏掉第一批文件事件？

目录事件和文件事件可能接近到达，补登记本身也需要时间。不要把“收到目录 Create”当成目录内所有历史变化都能补发；需要可靠处理时，应在加入新目录后扫描一次它的当前内容，并用业务层去重。

所以，Add 不递归不是故障，而是一个明确的单路径 API 设计。把“已有目录扫描”和“新增目录补登记”都纳入生命周期，才能得到可控的递归监听效果。