watchdog启动后事件不触发的主因是路径错误或权限/符号链接问题；on_modified重复触发源于编辑器写入策略；recursive=True不监听新子目录需手动补注册；CPU升高多因事件积压或异常未捕获。
watchdog 启动后没反应，FileSystemEventHandler 里方法不触发
常见现象是程序跑起来了，但改了文件、新建了文件，on_modified 或 on_created 根本不进。根本原因通常是监听路径没对上，或者权限/符号链接卡住了。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 用
os.path.abspath确保传给Observer.schedule()的路径是绝对路径，相对路径在某些工作目录下会静默失败 - 检查目标目录是否被挂载为只读、是否在 Docker 容器里（inotify 事件可能被限制）、是否是 NTFS 挂载点（Linux 下可能不支持 inotify）
- macOS 上如果监听的是 iCloud 同步目录，
on_modified可能被跳过——换到本地磁盘测试 - 避免监听软链接本身；要监听链接指向的目录，就先用
os.path.realpath()解析
on_modified 触发两次，或重复处理同一文件
这是 watchdog 最常被吐槽的问题：改一个文本文件，on_modified 被调两次，甚至三次。本质是编辑器写入策略导致的——比如 VS Code 先写临时文件再原子替换，或保存时先清空再重写内容。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 加简单去重逻辑：记录最近 1 秒内处理过的
event.src_path，重复则return - 优先用
on_closed_write（需继承PatternMatchingEventHandler并启用ignore_directories=False），它更接近“写入完成”语义 - 别依赖
event.is_directory判断类型，有些编辑器会先创建空文件再写内容，此时is_directory是False，但后续可能还有on_created事件
监听子目录时，recursive=True 不生效或漏事件
设了 recursive=True 却发现新增子目录里的文件没被监听到？不是 bug，是 watchdog 的设计行为：它只监听“已存在”的子树。新创建的子目录默认不会自动加入监听范围。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 在
on_moved或on_created中检测到新目录时，手动调用observer.unschedule()+observer.schedule()补监听（注意线程安全，用observer.add_handler_for_path()更稳妥） - 如果只是想监听整个目录树且结构稳定，启动前确保所有子目录已存在；否则就得自己维护监听树
- Windows 上
recursive=True实际走的是 ReadDirectoryChangesW，性能比 inotify 好但对硬链接支持弱；Linux/macOS 用 inotify/kqueue，对符号链接敏感
长时间运行后 CPU 占用升高，或监听失效
跑几个小时后 top 显示 Python 进程 CPU 持续 20%+，或某天突然不响应修改——大概率是事件队列积压、异常未捕获，或资源泄漏。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 在
on_any_event或各 handler 里包try/except Exception，尤其防止OSError: [Errno 2] No such file or directory（文件被删太快）打断主循环 - 定期清理旧事件：watchdog 默认用
queue.Queue，大小不限，可传queue.Queue(maxsize=1000)给Observer构造函数防爆 - 别在 handler 里做耗时操作（如读大文件、网络请求）；用
threading.Thread或asyncio.to_thread()拆出去 - Linux 下注意 inotify instance 数量上限：
cat /proc/sys/fs/inotify/max_user_instances，超了会静默失败；必要时调高或复用 observer
真正难的不是写监听逻辑，而是处理编辑器怎么写、系统怎么通知、权限怎么绕、资源怎么收——这些细节堆起来，才决定脚本能跑几天不掉链子。
