热重载本质是模块重载而非文件监控，需检测变更→清理sys.modules中相关模块→重新import；importlib.reload()不递归、不处理C扩展和实例，须手动管理依赖与引用。
热重载本质是模块重载，不是文件监控
Python 的 import 机制默认缓存已加载模块到 sys.modules，直接改代码不生效。所谓“热重载”，核心动作其实是：检测文件变更 → 清理旧模块 → 触发新 import。但 Python 原生的 importlib.reload() 有硬限制：它只接受已存在于 sys.modules 中的模块对象，且**不递归重载依赖项**，也不能处理 C 扩展或已绑定的类实例。所以别指望靠一层 reload() 就搞定整个包——你得自己管依赖拓扑和对象生命周期。
- 必须手动遍历并清理所有可能被污染的子模块（比如
my_package.submodule、my_package.submodule.utils） - 若自定义包里用了
from my_package import xxx这种导入方式，重载后原引用仍指向旧对象，需同步更新引用 -
reload()对已实例化的类对象无效，已有对象不会自动切换到新类定义
用 watchdog 监控文件变更比轮询更可靠
轮询（如 time.sleep(1) + 检查 mtime）容易漏触发或空耗 CPU；watchdog 基于系统 inotify / FSEvents，事件驱动、低延迟、支持递归监听。安装后只需监听包所在目录的 .py 文件修改事件，再触发重载逻辑即可。
- 监听路径必须是包的根目录（即含
__init__.py的目录），不能只监听__init__.py—— 子模块改动不会触发 - 注意排除
__pycache__和.pyc文件，否则可能因字节码生成时序问题误触发 - 事件回调中不要做耗时操作（如完整重载+测试），建议用队列或标志位异步处理，避免阻塞事件循环
重载前必须递归清理 sys.modules 中相关模块
假设你的包叫 myapp，位于 ./myapp/，那么不仅 myapp 要从 sys.modules 删除，所有以 myapp. 开头的键（如 myapp.api、myapp.api.v1）都得删干净。否则下次 import 会直接返回缓存的老模块。
import sys
def clear_package_modules(package_name):
to_remove = [k for k in sys.modules if k == package_name or k.startswith(package_name + ".")]
for k in to_remove:
del sys.modules[k]
- 删除顺序无关紧要，但必须在调用
importlib.import_module()前完成 - 如果包被其他第三方库间接导入（如通过
pkg_resources或importlib.metadata），这些地方不会自动更新，需额外兼容 - 某些框架（如 FastAPI）内部缓存了路由对应的函数对象，光重载模块不够，还得手动刷新其注册表
生产环境慎用，开发调试才适合
热重载不是为线上设计的。模块状态不一致、闭包变量残留、线程/协程中引用未更新、全局单例重复初始化……这些问题在长运行服务中极易引发难以复现的 bug。它只应在本地快速迭代时启用，且应明确禁用在 __main__ 模块或入口脚本中——因为 __main__ 无法被 reload()。
立即学习“Python免费学习笔记（深入）”；
- 务必加开关控制，默认关闭；可通过环境变量（如
ENABLE_HOT_RELOAD=1）或命令行参数激活 - 重载失败时不要静默吞掉异常，至少打印
traceback并保留旧模块，避免服务完全不可用 - 如果包里用了
atexit、signal或启动了后台线程，重载前得先显式清理，否则可能累积多个监听器或死锁
