Flask 如何关闭内置调试器与 reloader 以配合 IDE 外部调试器

用 IDE 自带调试器（外部调试器）调试 Flask 应用时，Flask 开发服务器的两个默认行为会干扰调试：内置调试器会抢先把未处理异常截下来，reloader 可能在断点停住时因代码变更触发意外重载。Flask 官方文档 调试章节 给出的做法是：应用保持 debug 模式，同时显式关闭内置调试器和 reloader。本文按 flask run 命令行和 app.run() 代码两条路径给出具体命令与验证方式。

先弄清楚要解决什么

外部调试器比内置调试器能力更强：可以在请求过程中、错误发生之前逐步执行代码，部分 IDE 调试器还支持 remote 模式调试另一台机器上运行的代码。但在 debug 模式下，开发服务器默认同时启用交互式调试器和 reloader，文档明确指出两者会干扰外部调试器，具体表现是：

• 内置调试器未关闭时，它会在外部调试器之前捕获未处理异常（Unhandled exception 先落在浏览器的交互式 traceback 页面上）；
• reloader 未关闭时，断点停留期间只要代码文件发生变化，就可能触发意外重载，打断调试会话。

同时，文档强调应用仍应处于 debug 模式。如果连 debug 模式一起关掉，Flask 会把未处理错误变成通用的 500 错误页，外部调试器同样拿不到可用的异常信息。所以目标配置是：debug 开，调试器关，reloader 关。

Flask 内置调试器在浏览器中的样子如下图所示（来自 docs/debugging.rst 的示例截图）：

路径一：用 flask run 命令行关闭

用 flask run 启动开发服务器时，在 server 文档 和 cli 文档 的示例基础上追加两个选项即可：

$ flask --app hello run --debug --no-debugger --no-reload

• --app hello：指向你的应用，替换成实际的应用模块或工厂调用方式；
• --debug：保留 debug 模式，必须保留，原因见上一节；
• --no-debugger：关闭内置交互式调试器（对应 CLI 选项 --debugger/--no-debugger，定义见 cli 源码）；
• --no-reload：关闭代码变更自动重载（对应 --reload/--no-reload）。

对照 cli 文档 中 flask --app hello run --debug 的文档示例输出，正常启用时启动横幅包含这几行：

$ flask --app hello run --debug
 * Serving Flask app "hello"
 * Debug mode: on
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
 * Restarting with inotify reloader
 * Debugger is active!
 * Debugger PIN: 223-456-919

上面为文档示例输出。加上 --no-debugger --no-reload 后，启动输出中不再出现 Restarting with inotify reloader 和 Debugger is active! / Debugger PIN 相关行，可以据此判断两个组件确实没有启动。

路径二：用 app.run() 在代码中关闭

从 Python 代码启动开发服务器时，app.run() 接收与 CLI 选项相似的参数来控制服务器（见 Flask.run 的文档字符串）。文档给出的写法：

app.run(debug=True, use_debugger=False, use_reloader=False)

按 server 文档 的要求，把这次调用放在主代码块里，避免之后用生产服务器导入运行时互相干扰：

if __name__ == "__main__":
    app.run(debug=True, use_debugger=False, use_reloader=False)

use_debugger、use_reloader 会通过 **options 转发给底层的 Werkzeug run_simple；如果不显式传入，两者默认跟随 debug 状态，所以在 debug=True 时必须显式传 False。

验证是否生效

两条路径关闭后，按 debugging 文档 描述的行为逐项确认：

1. 断点能命中：在 IDE 中于视图函数或业务代码里下断点，触发一个请求，外部调试器应停在断点处并可继续单步执行。文档说明外部调试器可用于"在请求期间、错误发生之前逐步执行代码"。
2. 异常归外部调试器：制造一个未处理异常，异常应由外部调试器捕获处理，而不是在浏览器里弹出内置调试器的交互式 traceback 页面。
3. 断点期间不再意外重载：断点停住时修改代码文件，服务器不应再触发 reload（reloader 关闭后不再监听代码变更）。

关闭后仍保留的一个默认行为

注意边界：即使关闭了内置调试器，开发服务器仍然会捕获未处理异常——文档解释这是为了避免服务器在任何错误时直接崩溃。如果你希望异常直接让服务器崩溃（文档原话是"通常你并不想要这样"），需要额外传入 passthrough_errors=True：

app.run(
    debug=True, passthrough_errors=True,
    use_debugger=False, use_reloader=False
)

另外两个容易混淆的边界：

• app.run() 文档中的 use_evalex=False 只是禁用交互式调试器里的代码执行，但调试器的 traceback 页面仍然激活，异常仍然先被内置调试器截住，不能替代 use_debugger=False。
• 开发服务器和内置调试器都不要用于生产环境：调试器允许从浏览器执行任意 Python 代码，虽然有 PIN 保护，但文档明确不建议依赖它做安全。生产部署应使用专门的服务器方案，参见 deploying 文档。