VSCode运行Flask失败主因是FLASK_APP未正确配置、Python解释器选错或launch.json未用"module":"flask"模式；必须通过Open Folder打开项目根目录，配置.env文件指定FLASK_APP和FLASK_DEBUG，并在launch.json中设置"module":"flask"、"args":["run","--host=127.0.0.1:5000","--no-debugger"]、"envFile":"${workspaceFolder}/.env"及正确解释器。
VSCode 运行 Flask 项目失败，八成是 FLASK_APP 找不到入口、Python 解释器选错，或调试配置绕过了 Flask CLI 机制——直接跑 python app.py 看似能启动，但热重载、flask shell、CLI 命令全失效。
为什么 flask run 在 VSCode 终端里能跑，但 Debug 按钮点不动
VSCode 的「运行和调试」默认不读你终端里 export FLASK_APP=app.py 的环境变量，也不自动激活虚拟环境。它只认 launch.json 里写的 env 或 envFile。
-
launch.json中必须用"module": "flask"，不是"program": "app.py"；否则跳过 Flask CLI，flask run的所有特性（比如--reload、--debug）都不生效 -
envFile必须指向项目根目录下的.env文件，内容为：FLASK_APP=app.py<br>FLASK_DEBUG=1
（注意：Flask ≥2.3 不再支持FLASK_ENV） - 如果项目结构是
src/app.py，FLASK_APP要写成src.app，且确保src在 Python 模块搜索路径里（即项目根目录需被设为工作区）
launch.json 配置必须包含哪些字段
缺一不可，否则要么找不到应用，要么端口绑定失败，要么热重载不触发。
-
"module": "flask"—— 强制走 Flask 官方启动流程 -
"args": ["run", "--host=127.0.0.1:5000", "--no-debugger"]——--no-debugger防止与 VSCode 调试器冲突；--host=显式指定地址端口，避免默认绑定localhost后被 Windows 防火墙拦截 -
"envFile": "${workspaceFolder}/.env"—— 不能写成相对路径或硬编码绝对路径 -
"justMyCode": true—— 关闭第三方库断点干扰，但调试 Flask 自身逻辑时可临时设为false
完整片段示例：
立即学习“Python免费学习笔记（深入）”；
python-docx Skill功能概述python-docx Skill是一项面向实际任务的技能，主要用于本Skill提供使用python-docx生成专业Word文档的标准方法和最佳实践；生成安全服务方案文档；核心要点生成技术架构设计文档；生成任何需要专业排版的Word文档；核心库 : python-docx；使用与执行辅助库 : docx.shared , docx.enum , docx.oxml.ns；标准代码模板；1. 文档初始化；2. 字体设置（必须！它将相关步骤、工具调用和结果整理方式集
{
"name": "Flask: Run",
"type": "python",
"request": "launch",
"module": "flask",
"args": ["run", "--host=127.0.0.1:5000", "--no-debugger"],
"envFile": "${workspaceFolder}/.env",
"justMyCode": true
}
Python 解释器选错导致 ImportError: No module named 'flask'
VSCode 底部状态栏显示的 Python 路径，必须指向你 pip install flask 那个环境。常见陷阱：
- 选了系统 Python（如
/usr/bin/python3），但 flask 只装在 venv 里 - 用了 Poetry，却选了全局
python，而不是.venv/bin/python（Poetry 默认把 venv 放在项目内.venv下） - Windows 上路径含空格（如
C:\Users\My Name\...），导致 launch.json 解析失败；建议项目路径避开空格和中文
验证方法：在 VSCode 集成终端中执行 python -c "import flask; print(flask.__version__)"，有输出才真正可用。
热重载（--reload）在调试时失效怎么办
VSCode 调试器和 Flask 的 reload 机制会抢端口、争进程控制权，导致改代码后没反应，甚至报 Address already in use。
- 开发阶段优先用终端命令：
flask run --reload --host=127.0.0.1:5000，配合 VSCode 的「保存即运行」任务（tasks.json）更稳 - 非要调试时，先关掉
--reload，用"args": ["run", "--no-reload"]；断点命中后再手动重启 - 别在
app.py顶层写数据库连接、文件读取等初始化逻辑——热重载会反复执行，引发连接泄漏或 PermissionError
最易被忽略的一点：VSCode 的「自动保存」必须打开（files.autoSave 设为 onFocusChange 或 afterDelay），否则文件没真正落盘，Flask reload 根本检测不到变化。
