VSCode 调试 Flask 必须使用 "module": "flask" 模式、正确配置 .env 文件（UTF-8无BOM、FLASK_APP=app.py）、以文件夹方式打开项目并手动选择虚拟环境解释器，三者缺一不可。

VSCode 能运行 Flask，但直接点「运行」或按 F5 几乎必然失败——不是代码问题，而是它默认没走 Flask 官方启动流程，FLASK_APP 不生效、断点进不去、url_for() 报错都源于此。

launch.json 必须用 "module": "flask"，不能写 "program": "app.py"

用 "program" 是让 Python 直接执行脚本，绕过了 Flask CLI；"module": "flask" 才等价于终端里运行 python -m flask run，热重载、flask shell、上下文感知（比如 url_for()）才真正可用。

• 断点打在路由函数里不触发？大概率是用了 "program" 模式，Werkzeug fork 后 VSCode 只 attach 主进程
• 如果入口是工厂函数（如 create_app()），"args" 得改成 ["--app", "app:create_app", "run", "--no-reload"]，注意格式是 模块名:函数名
• --no-reload 是调试阶段刚需，避免子进程干扰断点；开发时可去掉，但别在 launch.json 里留着它跑生产

.env 文件必须存在、路径写死、内容无空格

VSCode 调试器完全不读终端里的 export FLASK_APP=app.py，只认 envFile 指定的文件。路径错、编码错、格式错，都会导致 Could not locate a Flask application。

FastAPI Flask Proxy

FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。

下载

• 文件必须放在项目根目录（即 app.py 所在目录），命名为 .env，编码为 UTF-8 无 BOM（Windows 记事本易带 BOM，建议用 VS Code 自带保存）
• launch.json 中必须显式写 "envFile": "${workspaceFolder}/.env"，不能简写成 ".env" 或绝对路径
• .env 内容严格两行，无空行、无多余空格：
  FLASK_APP=app.py
FLASK_DEBUG=1
FLASK_ENV 在 Flask ≥2.3 已弃用，写进去反而可能警告或报错
• 如果主文件在 src/app.py，FLASK_APP 要写成 src.app，且必须用 File → Open Folder 打开整个文件夹，否则 Python 找不到模块

Python 解释器必须手动选对，且终端要自己激活虚拟环境

底部状态栏显示了 venv 路径 ≠ 终端已激活。没激活就 pip install flask，包实际装到了系统 Python，import flask 必然失败。

• 按 Ctrl+Shift+P（macOS 是 Cmd+Shift+P），输入 Python: Select Interpreter，从列表中选带 venv、.venv 或 pyenv 字样的路径
• 选完后，新开集成终端，运行 python -c "import flask; print(flask.__version__)" 验证是否能 import
• 用 Poetry 的话，别选 poetry 可执行文件本身，要选 poetry env info --path 返回路径下的 python（通常在 .venv/bin/python）
• Windows 下激活命令是 .\venv\Scripts\activate，Linux/macOS 是 source venv/bin/activate；VSCode 新建终端不会自动继承设置，这一步必须手动做

最容易被忽略的是三者对齐：launch.json 用 "module": "flask"、.env 显式声明入口、项目以文件夹方式打开——漏掉任何一个，Working outside of application context 就会准时出现。