Python 模块热重载的 watchdog + reload 方案

importlib.reload失败主因是模块引用链未更新和全局状态残留，需确认sys.modules中模块存在、避免多次导入、清除装饰器缓存并重建实例；watchdog应过滤临时文件并依系统选合适observer。

watchdog 监听文件变化但 importlib.reload 失败？检查模块引用链

模块热重载失败，八成不是 watchdog 没触发，而是 importlib.reload 作用对象错了。它只能重载已导入的模块对象，不能靠路径字符串 reload；如果模块是被其他模块间接导入（比如 A → B → C），只 reload C 不会更新 A 或 B 中对 C 的引用。

• 用 sys.modules.get("module_name") 确认目标模块是否已在内存中，且值不为 None
• 避免 reload 被多次 import 的模块——比如 from x import y 后又 import x，reload x 不影响已绑定的 y
• 若模块含全局状态（如缓存字典、类实例），reload 后旧对象仍存活，新模块代码不会自动接管它们

用 watchdog 监听 .py 文件时，忽略 __pycache__ 和编辑器临时文件

不加过滤会导致频繁误触发：VS Code 的 .py~、pycharm 的 .py.swp、python 自动生成的 __pycache__/xxx.cpython-311.pyc 都可能被当成源码变更。

• 在 FileSystemEventHandler 子类的 on_modified 中，先判断 event.src_path.endswith(".py")
• 跳过 os.path.basename(event.src_path).startswith(".") or "pycache" in event.src_path
• linux/macos 下注意编辑器可能先写临时文件再原子 rename，建议监听 on_created + on_moved 并做后缀校验，比只靠 on_modified 更稳

importlib.reload 后函数对象没更新？因为闭包和装饰器缓存了旧引用

即使模块 reload 成功，调用栈里已存在的函数对象（尤其是被装饰器包装、或作为闭包自由变量捕获的）仍指向旧版本代码，不会自动刷新。

• 装饰器如 @lru_cache、@cached_property 必须手动清除：调用 func.cache_clear()
• 类方法被重载后，已有实例的 self.method 仍是旧绑定方法，需重建实例或显式赋值 obj.method = type(obj).method.__get__(obj, type(obj))
• 避免在模块顶层执行“单例初始化”，比如 APP = flask(__name__) —— reload 后 APP 还是旧实例，新模块里的配置变更无效

windows 下 watchdog 占用 CPU 高？换用 winapi 原生事件

默认的 PollingObserver 在 Windows 上轮询效率低；WindowsApiObserver 利用系统 ReadDirectoryChangesW，延迟低且几乎不耗 CPU，但需确保监听路径不跨网络驱动器（否则退化为 polling）。

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

• 显式指定 observer：from watchdog.observers import WindowsApiObserver，构造时传 observer = WindowsApiObserver()
• 路径必须是本地 NTFS 卷，Z: 映射盘或 servershare 会静默 fallback 到 polling，可用 os.stat(path).st_file_attributes & stat.FILE_ATTRIBUTE_LOCAL_DRIVE 粗略判断（非绝对）
• 若项目需跨平台，别硬编码 observer 类型，改用 Observer 基类 + try/except 捕获 NotImplementedError 后降级

真正卡住的往往不是 reload 本身，而是模块间隐式依赖、运行时对象生命周期、以及不同操作系统对文件事件的实现差异。盯住 sys.modules 里的对象引用，比反复调 reload 有用得多。