watchdog启动后无反应需检查事件处理器注册和事件循环阻塞；必须显式注册处理器并用join()或sleep()维持主线程；on_modified可能因编辑器保存机制触发多次，建议去重或监听on_closed_write。
watchdog 启动后没反应？检查事件处理器注册和事件循环是否阻塞
watchdog 不是“启动就自动打印所有变化”的黑盒，它需要你显式注册事件处理器，并且必须保持主程序运行（不能启动完就退出）。常见错误是写了 Observer 实例、调用了 start()，但没加 time.sleep() 或没接 join()，导致主线程立刻结束，后台监听直接终止。
- 必须用
observer.join()阻塞主线程，或在循环中用time.sleep(1)维持进程存活 - 事件处理器（如继承
FileSystemEventHandler的类）要重写具体方法：on_created、on_modified等，不是只写on_any_event就万事大吉 - 如果用在 Flask/FastAPI 后台里，别把
observer.start()放在路由函数内——每次请求都新建 observer，资源泄漏且无法持续监听
on_modified 触发两次？这是编辑器保存机制导致的正常现象
多数现代编辑器（VS Code、Sublime、PyCharm）保存文件时会先写临时文件再原子替换，或启用备份/swap 文件策略，结果触发多次 on_modified 甚至 on_deleted + on_created。这不是 watchdog bug，而是文件系统真实行为。
- 不要依赖单次
on_modified做关键业务（比如立即解析日志），加简单去重：缓存最近 1 秒内处理过的event.src_path - 优先监听
on_closed_write（需用PollingObserver或 Linux 下 inotify +inotify库），它更接近“真正写完”时刻 - Windows 上默认用
ReadDirectoryChangesW，对某些编辑器行为更稳定；macOS 则依赖 FSEvents，本身就有合并通知机制
监控子目录不生效？注意 recursive 参数和路径权限
observer.schedule(handler, path, recursive=True) 中的 recursive 控制是否监听子目录，但很多人忽略两点：一是路径末尾斜杠影响实际匹配（尤其符号链接场景），二是当前用户对目标路径是否有读取+执行（x）权限——缺任一权限，子目录根本不会被纳入监听范围。
- 用
os.path.abspath(path)规范路径，避免相对路径引发的层级误判 - Linux/macOS 下执行
ls -ld /target/dir确认当前用户有r-x权限；Windows 下检查文件夹“安全”选项卡中用户是否具备“列出文件夹内容”和“读取”权限 - 若监控网络挂载点（如 NFS、Samba），
recursive=True可能失效或极不稳定，改用PollingObserver更可靠
watchdog 在 Docker 容器里监听不到变化？宿主机文件系统事件不透传
Docker 默认不会把宿主机 inotify 事件转发进容器，尤其是挂载 hostPath 或 bind mount 时，容器内看到的是静态快照，inotify 监听器收不到任何信号。这不是 Python 或 watchdog 的问题，是容器隔离机制决定的。
立即学习“Python免费学习笔记（深入）”；
- Linux 宿主机启动容器时加
--privileged或至少--cap-add=SYS_INOTIFY_INIT（部分内核版本支持） - 更通用方案：改用
PollingObserver替代默认Observer，它靠轮询 stat 时间戳判断变更，不依赖 inotify —— 性能略低，但跨环境一致 - 如果用 Docker Desktop for Mac/Windows，注意其文件共享层（gRPC-FUSE）本身就不支持 inotify 透传，
PollingObserver是唯一可行选择
最常被绕开的点：watchdog 的事件回调是在独立线程里执行的，如果你在回调里做耗时操作（比如同步上传文件、调用外部 HTTP 接口），会堆积事件队列，后续通知延迟甚至丢失。真要审计级可靠性，得加队列 + 工作线程池，而不是在 on_created 里直接 requests.post()。
