如何配置 VSCode 的 launch.json 调试 Flask 应用？

先确认现象

调试 Flask 应用时最常见的异常是：点击 VSCode 的“运行和调试”按钮后，终端一闪而过，没有任何错误输出，或者断点根本不停。另一种情况是应用正常启动了，但所有断点都显示为“未验证”（空心圆圈），调试器没有附加到进程上。

遇到这类现象，我通常会先查看 VSCode 的“调试控制台”输出。如果输出显示类似“module 'flask' has no attribute 'run'”或“ImportError: cannot import name 'app'”，说明 launch.json 里 program 字段指向了错误的入口点。

容易误判的地方

很多人第一反应是检查 Flask 代码的语法或路由是否正确，但大多数情况下代码本身没问题。调试不生效的根源在于 launch.json 的配置没有匹配实际应用的入口模式。

这里有一个典型误区：直接在 program 字段写 "${workspaceFolder}/app.py"，然后期望像执行普通 Python 脚本那样启动 Flask 应用的 run() 方法。但 Flask 开发服务器内部使用了子进程或 reloader，VSCode 的调试器默认只 attach 到主进程，当 reloader 重启子进程时，调试连接就会断开。正确做法是让调试器直接启动应用对象，而不是通过 flask run 命令间接启动。

另一个容易忽略的点是环境变量 FLASK_APP 和 FLASK_ENV。如果 launch.json 中的 env 块没有设置这些，Flask 可能找不到应用实例，进而无法从启动时挂载调试器。

建议的处理顺序

我会按以下步骤排查和修复：

确认 Flask 应用的入口文件里是否包含 app.run() 调用，并且该调用只在 if __name__ == '__main__': 块内。
打开 VSCode 的 .vscode/launch.json，检查当前配置的 type（应为 python）、request（launch 或 attach）、program（指向入口文件）、args（可选端口等）。
删除或注释掉 launch.json 中可能残留的旧配置，重新通过“添加配置”按钮选择“Flask”模板（如果 VSCode 的 Python 扩展提供了的话），或者手动撰写一个稳定配置。
在 launch.json 的 env 块中显式设置 FLASK_APP 为入口模块名（如 "app.py" 的模块名是 "app"），同时设置 FLASK_ENV 为 development 以便启用调试模式。
先尝试不带断点运行一次，确认应用正常启动并能访问。然后再打上断点重启调试会话。

配置或命令示例

以下是我在项目中实际使用过的一条 launch.json 配置，适用于大多数 Flask 单文件应用：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Flask",
            "type": "python",
            "request": "launch",
            "module": "flask",
            "env": {
                "FLASK_APP": "app.py",
                "FLASK_ENV": "development",
                "FLASK_DEBUG": "1"
            },
            "args": [
                "run"
            ],
            "jinja": true
        }
    ]
}

注意这里使用了 "module": "flask" 而非 "program"，相当于执行 python -m flask run。这样调试器会直接启动 flask 模块，然后在 flask 内部加载应用对象，Reloader 的干扰会比直接用 program 小。但如果你应用使用了工厂模式（create_app），这种配置可能导致断点无法在 factory 函数内停住，需要改用 "program": "${workspaceFolder}/app.py" 并确保文件里有 app.run() 调用。

另外一种常见写法是：

{
    "name": "Python: Flask (program)",
    "type": "python",
    "request": "launch",
    "program": "${workspaceFolder}/run.py",
    "args": [],
    "env": {
        "FLASK_APP": "myapp",
        "FLASK_ENV": "development"
    }
}

这种写法适用于将启动逻辑单独写在 run.py 中，且 run.py 内容类似：

from myapp import app
app.run(debug=True, use_reloader=False)

关键点在于关闭 reloader（use_reloader=False），否则调试器会因子进程重启而断开。如果一定要保留 reloader，则需要配置 "request": "attach" 并让 flask 先以调试模式启动，再手动附加。

验证方法

配置完成后，先不设断点，按 F5 启动调试。观察终端输出，检查是否有类似 “Debugger is active!” 或 “* Debug mode: on” 字样。然后在浏览器访问应用的某个路由，确认页面正常返回。接着在视图函数或某个导入的模块中设置一个普通断点（点行号左侧，圆点应为实心红色），再次发起请求。如果程序在断点处暂停，调试器变量区出现当前变量，说明调试成功。如果断点仍然是空心，说明调试器没有正确附加，需要检查 launch.json 的 type 是否为 python，以及 Python 扩展是否已正确安装激活。

回滚和风险

修改 launch.json 前建议备份原文件，或使用版本控制（git）。如果新配置导致调试完全无法启动，最简单的回滚是还原到上一个已知可用的配置。风险方面，使用 "module": "flask" 方式时，如果 Flask 版本差异导致命令行参数变化，可能会报错。另外，强制关闭 reloader 会导致修改代码后需要手动重启调试会话，但这对于调试来说是可控的折中。如果项目使用了 Flask-Script 或 Click 自定义命令，可能需要调整 args 参数。遇到不确定的情况，可以先在 VSCode 的“运行和调试”侧边栏中删除该配置，重新通过“添加配置”下拉菜单里的“Flask”模板生成一份初始配置，再根据实际入口微调。

后续维护

当项目结构变化（比如从单文件改为包结构）或 Flask 版本升级时，记得同步更新 launch.json 中的 FLASK_APP 和 FLASK_ENV。如果团队多人开发，建议将 .vscode/launch.json 加入版本控制，并在 README 中说明调试配置的用法。另外，可以搭配 .vscode/settings.json 设置 "python.terminal.activateEnvironment": true，确保调试时自动激活虚拟环境。这样能减少环境变量不一致导致的问题。