VSCode启动Flask项目失败主因是未用官方CLI流程：应配置launch.json的"module": "flask"而非"program": "app.py"，并确保.env文件存在、编码UTF-8无BOM、Python解释器正确选择、以文件夹方式打开项目。
VSCode 启动 Flask 项目失败，90% 是因为没走 Flask 官方 CLI 流程，而是直接运行 app.py —— 这会导致热重载失效、flask shell 不可用、环境变量不生效，甚至报 Working outside of application context。
为什么 launch.json 要用 module 而不是 program
直接设 "program": "app.py" 是在 Python 解释器里执行脚本，绕过了 Flask 的命令行入口；而 "module": "flask" 等价于终端里运行 python -m flask run，这才是官方推荐的启动方式。
-
flask run自动读取FLASK_APP和FLASK_DEBUG，支持 --reload、--debugger、--host 等参数 - 断点在路由函数里能正常命中；
flask shell可用；url_for()等上下文敏感函数不会报错 - 若仍想用
program方式（比如调试if __name__ == '__main__': app.run()），必须加"args": ["--no-reload"]，否则调试器会 fork 出两个进程，断点只在父进程生效
.env 文件必须存在且路径正确
VS Code 的调试器不继承终端的 shell 环境变量，export FLASK_APP=app.py 在终端里有效，但在 F5 启动时完全无效。
- 在项目根目录（即
app.py所在目录）新建.env文件，内容为： FLASK_APP=app.py-
FLASK_DEBUG=1（FLASK_ENV=development已被弃用，Flask ≥2.3 会警告） - 在
launch.json中显式指定"envFile": "${workspaceFolder}/.env"，路径不能写错，也不能漏掉引号 - 文件编码必须是 UTF-8 无 BOM，Windows 记事本保存时容易带 BOM，建议用 VS Code 自带保存功能
Python 解释器选错会导致 ImportError: No module named 'flask'
VS Code 默认可能选了系统 Python 或其他虚拟环境，而 flask 是 pip 安装在某个 venv 里的。
- 按
Ctrl+Shift+P（macOSCmd+Shift+P），输入Python: Select Interpreter - 从列表中选带
venv、env或pyenv字样的路径，例如：./venv/Scripts/python.exe（Windows）或./venv/bin/python（macOS/Linux） - 选完后，底部状态栏会显示该路径；可打开集成终端，运行
python -c "import flask; print(flask.__version__)"验证 - 若用 Poetry，不要选
poetry可执行文件本身，要选poetry env info --path返回路径下的python（通常在.venv/bin/python）
端口绑定与防火墙问题常被忽略
默认 flask run 绑定 127.0.0.1:5000，但某些 Windows 防火墙策略会拦截本地回环地址的调试连接，导致浏览器打不开或超时。
- 在
launch.json的args中显式指定 host 和 port：["run", "--host=127.0.0.1", "--port=5000"] - 如需局域网访问（比如手机调试），改用
--host=0.0.0.0，但仅限可信网络，切勿暴露到公网 - 若提示
Address already in use，先在终端运行lsof -i :5000（macOS/Linux）或netstat -ano | findstr :5000（Windows）查 PID，再kill -9 PID或taskkill /PID PID /F
最易被忽略的一点：VS Code 必须用 File → Open Folder 打开整个项目文件夹，而不是双击打开单个 app.py —— 否则 ${workspaceFolder} 解析错误，.env 和 launch.json 都会失效。
