Python监控文件系统变更最常用稳定方案是watchdog库，它跨平台、支持递归监听、事件粒度细且异步友好；安装后可监听创建、修改、删除等7类事件，并通过路径过滤、去重和限定递归层级优化性能。
Python中监控文件系统变更，最常用且稳定的方案是使用 watchdog 库。它跨平台（Windows/macOS/Linux）、支持递归监听、事件粒度细（创建、修改、删除、重命名等），并且设计为异步友好，适合集成进脚本或服务中。
安装与基础监听
通过 pip 安装：
pip install watchdog
最小可用示例：监听当前目录下所有文件变动
from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler
class MyHandler(FileSystemEventHandler):
def on_modified(self, event):
if not event.is_directory:
print(f"文件被修改: {event.src_path}")
observer = Observer()
observer.schedule(MyHandler(), path=".", recursive=True)
observer.start()
try:
while True:
pass
except KeyboardInterrupt:
observer.stop()
observer.join()
关键事件类型与用途
watchdog 提供 7 类核心事件，按实际需求选择重写对应方法：
- on_created：新建文件或目录（含复制、粘贴、新建文档）
- on_deleted：文件或目录被删除（回收站内不触发，彻底删除才触发）
- on_modified：文件内容被写入（保存动作），或目录下有新增/删除项（注意：频繁写入可能触发多次）
- on_moved：重命名或移动（含跨目录剪切），同时提供 src_path 和 dest_path
- on_closed_write：仅 Linux/macOS 有效，表示文件写入完成并关闭（比 on_modified 更可靠判断“保存完毕”）
避免重复触发与性能优化
文本编辑器（如 VS Code、Sublime）保存时可能先写临时文件再原子替换，导致多个事件；高频日志写入也可能刷屏。建议：
- 对 on_modified 做路径后缀过滤（如只响应 .py 或 .json）
- 用 time.sleep(0.1) + 简单去重（记录最近 1 秒内处理过的文件路径）
- 监听时设置 recursive=False 限定层级，避免遍历过深目录
- Linux 下优先用 InotifyObserver（watchdog 自动选用），比通用 FSEventsObserver 更轻量
实战：监听配置文件自动重载
常见需求：config.yaml 修改后，程序自动加载新配置。可结合 threading.Event 或 queue.Queue 实现安全通信：
import yaml
from watchdog.events import FileSystemEventHandler
class ConfigReloader(FileSystemEventHandler):
def __init__(self, config_path, reload_callback):
self.config_path = config_path
self.reload_callback = reload_callback
def on_modified(self, event):
if event.src_path == self.config_path:
try:
with open(self.config_path) as f:
new_cfg = yaml.safe_load(f)
self.reload_callback(new_cfg)
except Exception as e:
print(f"配置加载失败: {e}")
将该 handler 绑定到 Observer 即可实现热更新，无需重启进程。
