flask 开启 debug 模式后自动重载不生效，常见原因是默认的 stat 监听机制在某些系统（尤其是 linux/macos 文件系统或 docker 环境）下无法可靠捕获文件变更；安装 watchdog 库可启用更稳定的 inotify 或 fsevents 监听，彻底解决重载失效问题。
Flask 的开发服务器在 debug=True 或通过 flask run --debug 启动时，会启用自动重载（auto-reloader）和调试器。但其默认依赖 stat 方式轮询检测文件修改时间戳——该方式在某些场景下表现不可靠：例如 NFS 挂载、WSL2、Docker 容器内、某些 IDE 的文件保存策略（如 VS Code 的“延迟写入”或“Atomic 保存”），都可能导致 stat 无法及时感知变更，从而出现控制台显示 * Restarting with stat 却实际不重启的现象。
✅ 正确解决方案是安装 watchdog：
pip install watchdog
安装后无需修改代码——Flask 会自动检测 watchdog 是否可用，并优先使用其底层事件驱动机制（Linux 下为 inotify，macOS 下为 fsevents，Windows 下为 ReadDirectoryChangesW）。启动时你会看到日志变为：
* Restarting with watchdog (inotify) * Debugger is active! * Debugger PIN: xxx-xxx-xxx
此时保存 .py 或模板文件（如 templates/index.html）将立即触发服务重启。
⚠️ 注意事项：
- 不要同时使用 app.run(debug=True) 和 flask run 命令：二者冲突。推荐统一使用命令行方式（即删除 if __name__ == '__main__': app.run(...)，改用 flask run --debug 或设置环境变量后执行 flask run）；
- 确保 .env 文件被正确加载：load_dotenv() 需在 Flask(__name__) 实例创建之前调用（你当前代码已满足）；
- 若使用 PyCharm/VS Code，请关闭「Safe Write」（安全写入）选项（它会先写临时文件再替换，干扰监听），路径示例：
VS Code → 设置 → Files: Safe Write → 取消勾选；
PyCharm → Settings → System Settings → 「Use "safe write"」→ 取消勾选； - watchdog 在 Docker 中需确保宿主机文件系统事件能穿透到容器（Linux 主机通常支持；macOS/Windows 需启用 docker run --volume-driver=local 或使用 docker-sync 等方案）。
? 补充：若仍无效，可手动指定重载器类型验证：
flask run --debug --reloader-type watchdog
总之，watchdog 是 Flask 开发体验的关键依赖——它不是可选插件，而是现代开发环境下保障热重载稳定性的事实标准。
