watchdog监听需选稳定事件类型并去重：优先on_created/on_moved，修改事件加100–500ms去抖；缩小监听范围、分层递归；on_deleted易丢失，应监听on_moved并兜底轮询；后台运行需正确启停线程，避免阻塞主线程。

watchdog 能可靠监听文件变更，但默认行为容易漏事件或触发多次——关键在事件类型选择和去重策略。

如何注册监听并避免重复触发修改事件

Linux/macOS 下 inotify 和 FSEvents 默认对单次保存可能发出多个 FileModifiedEvent，尤其编辑器（如 VS Code）会先写临时文件再原子替换。直接响应每个 on_modified 会导致重复处理。

• 优先监听 on_created 和 on_moved，它们更稳定；对必须响应修改的场景，加 100–500ms 去抖（debounce），用 time.time() 记录上次处理时间
• 避免监听整个项目根目录，缩小范围到具体子目录（如 "./src"），减少无关事件干扰
• 使用 RecursiveEventHandler 时注意：递归监听深层嵌套目录会显著增加内核事件队列压力，大项目建议分层监听

为什么 on_deleted 有时收不到，以及如何补救

on_deleted 在文件被快速创建又删除（如临时文件）、或跨分区移动时大概率丢失——这是底层 inotify 的限制，不是 watchdog bug。

macOS UI 自动化技能包 —— 用 Python 控制你的 Mac

让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限

下载

• 改用监听 on_moved 并检查 event.dest_path 是否为空，部分编辑器删除实际走的是 rename 到 /dev/null 或类似路径
• 对关键文件，可配合定期轮询（如每 2 秒调用 os.path.exists()），只用于兜底，不作为主逻辑
• Windows 下 ReadDirectoryChangesW 对已删除句柄的监控更弱，务必设置 timeout=1 避免阻塞

如何让 watchdog 在后台安静运行不卡主线程

watchdog 默认启动独立线程，但若在主线程中直接调用 observer.start() 后没做任何等待，脚本会立即退出，监听失效。

立即学习“Python免费学习笔记（深入）”；

• 用 observer.join() 阻塞主线程（适合简单脚本），或捕获 KeyboardInterrupt 后调用 observer.stop()
• 若集成到 Flask/FastAPI 中，需将 observer 实例挂载为应用全局变量，并在 app.on_event("startup") 中启动、shutdown 中停止
• 不要在事件回调里做耗时操作（如读大文件、网络请求），应丢进 threading.Thread 或 asyncio.to_thread() 异步执行

真正难的不是注册监听，而是判断“这次变更是否真的需要响应”——文件锁状态、编辑器保存模式、NFS 挂载延迟，都可能让同一个用户操作产生不同事件序列。建议先用 LoggingEventHandler 打印原始事件，观察真实行为再写业务逻辑。