watchdog是跨平台文件监听的事实标准，封装inotify/kqueue/Windows API，避免轮询和平台适配；需确保路径存在且有权限，注意事件类型区分与大目录监听限制。
用 watchdog 监听文件变化最省心
Python 标准库没有开箱即用的跨平台文件监听方案，watchdog 是目前事实标准。它封装了各系统底层机制（inotify、kqueue、Windows API），避免你手动轮询或写平台特异性代码。
常见错误现象：OSError: [Errno 2] No such file or directory —— 多因监听路径不存在或权限不足；FileNotFoundError 在监听启动前就删掉目标目录也会触发。
- 安装只需
pip install watchdog，不依赖 C 编译（纯 Python 后端可选watchdog-gevent） - 监听路径必须存在，且进程需有读取+执行（
x）权限（Linux/macOS）或“遍历文件夹”权限（Windows） - 默认递归监听子目录，设
recursive=False可关闭，但注意：某些事件（如重命名）仍可能跨层级触发 - 事件回调函数里别做耗时操作，否则会阻塞事件队列；建议丢进线程池或发消息到队列
FileSystemEventHandler 的事件类型怎么区分
不是所有变化都叫“修改”。watchdog 把底层事件映射成 6 种明确的子类，对应真实行为，而不是靠文件后缀或时间戳猜。
使用场景：比如只想处理新上传的图片，就得过滤 FileCreatedEvent 并检查 event.src_path 是否以 .jpg 结尾；又比如要等文件写完再处理，得等 FileClosedEvent（而非 FileModifiedEvent，后者在写入中途就会高频触发）。
立即学习“Python免费学习笔记（深入）”；
-
FileCreatedEvent：新建文件或目录（含touch、mkdir） -
FileDeletedEvent：文件或目录被删除（注意：回收站不算删除，是移动） -
FileModifiedEvent：文件内容被写入（每次write()都可能触发） -
FileClosedEvent：文件描述符关闭（较可靠判断“写入完成”，但 Windows 上不保证 100% 触发） -
FileMovedEvent：重命名或移动（src_path和dest_path都有值） -
Dir*开头的类同理，专用于目录操作
为什么 inotify 监听大目录会失败
Linux 下 watchdog 默认走 inotify，但它对每个监听路径消耗一个 inotify 实例，而系统有硬限制（通常 /proc/sys/fs/inotify/max_user_watches 默认 8192）。监听整个 /home 或 Git 仓库这种几千文件的目录，很容易超限，报错 OSError: [Errno 24] Too many open files。
- 临时解决：用
sudo sysctl fs.inotify.max_user_watches=524288提高上限（重启失效） - 长期方案：只监听必要子路径，避开
node_modules、.git等大目录（ignore_patterns=['*.pyc', '.git', 'node_modules']） - 不要监听挂载点（如
/mnt/nas），CIFS/NFS 文件系统可能不支持 inotify，降级为轮询（性能差十倍以上） - macOS 的
kqueue没这问题，但对符号链接监听不稳定，建议用os.path.realpath()归一化路径
轮询（PollingObserver）什么情况下不得不用
当目标环境不支持内核事件（比如 Docker 容器没挂载 /proc、某些 NFS 共享、旧版 WSL1），watchdog 会自动 fallback 到轮询，但更稳妥的做法是显式指定 PollingObserver，并控制节奏。
性能影响明显：每秒扫一次目录，IO 压力随文件数线性增长；1000 个文件约增加 5–10ms CPU 时间，上万文件就卡顿。
- 初始化时传
timeout=5（单位秒），避免默认 1 秒太频繁；值太大则事件延迟高 - 轮询无法捕获“瞬间创建又删除”的文件（
tmpfile类型），这类需额外加日志或改用其他机制 - Windows 上如果启用了“缩略图缓存”，轮询可能误报
Thumbs.db修改，建议忽略该文件 - 别在同一个路径混用
Observer和PollingObserver，事件可能重复触发
真正难的是事件语义理解——比如编辑器保存时先写临时文件再原子替换，实际触发的是 FileMovedEvent 而非 FileModifiedEvent。盯住具体工具的行为比死记文档管用。
