flask 开启 debug 模式后自动重载不生效，常见原因是默认的 stat 监控方式在某些系统（尤其是 wsl、docker 或 nfs 挂载目录）下无法可靠捕获文件变更；安装 watchdog 可启用更健壮的文件系统事件监听机制，彻底解决重载失灵问题。
Flask 的开发服务器内置了自动重载（auto-reloader）功能，当 debug=True 时会默认启用。但其底层依赖文件系统监控策略：默认使用 stat 轮询（定期检查文件修改时间），该方式轻量但存在明显局限——在以下场景中极易失效：
- 使用 Windows Subsystem for Linux（WSL1/WSL2）开发；
- 项目位于 Docker 容器中且源码通过 volume 挂载；
- 文件存储于网络文件系统（如 NFS、Samba）或某些云同步盘（如 OneDrive、iCloud）；
- 系统 I/O 延迟高或文件时间戳未及时更新（如编辑器保存策略差异）。
虽然终端显示 * Restarting with stat 和 * Debugger is active!，看似一切正常，但 stat 无法感知实际变更，导致保存代码后服务静默、无重启日志、页面不刷新。
✅ 根本解决方案：安装 watchdog
watchdog 是一个跨平台的文件系统事件监控库，支持 inotify（Linux）、kqueue（macOS）、ReadDirectoryChangesW（Windows）等原生事件接口，响应快、精度高、资源占用低。
执行以下命令安装：
pip install watchdog
安装后无需修改代码——Flask 会在启动时自动检测 watchdog 是否可用，并优先使用它替代 stat：
* Serving Flask app 'app' * Debug mode: on * Running on http://127.0.0.1:5000 * Restarting with watchdog (inotify) ← 关键变化！ * Debugger is active! * Debugger PIN: xxx-xxx-xxx
此时，任意 Python 模块（如 app.py）、模板（templates/）或静态资源（static/）发生变更，Flask 将立即触发重启并输出 * Detected change in '...'; reloading 日志。
⚠️ 注意事项：
- watchdog 在 macOS 上需额外安装 pyobjc-framework-Cocoa pyobjc-framework-FSEvents（通常 pip install watchdog 会自动处理）；
- 若使用 flask run 命令（而非 python app.py），确保 .env 中 FLASK_DEBUG=1 生效（Flask 2.3+ 已默认启用重载，但仍推荐显式设置）；
- 避免在生产环境启用 debug=True 或 use_reloader=True，仅限开发阶段使用；
- 若仍不生效，请检查文件是否被 IDE（如 VS Code 的“Atomic Save”）或编辑器以临时文件方式写入——可尝试关闭相关选项或改用 --reloader-type watchdog 显式指定（Flask ≥ 2.2）。
总结：Flask 重载失败 ≠ 配置错误，而是监控机制与运行环境不匹配。watchdog 是官方推荐的增强方案，一行安装即可让开发体验回归流畅。
