vscode调试flask断点不触发的直接原因是使用"program": "app.py"启动，绕过flask cli导致werkzeug子进程无法被attach；正确做法是launch.json中设"module": "flask"，配合args指定run命令及--no-reload、--no-debugger等参数，并确保.env文件位置正确、格式规范。
launch.json 必须用 "module": "flask"，不能用 "program"
VSCode 点 F5 调试时断点不触发、改代码没热重载、flask shell 命令报错——根本原因是用了 "program": "app.py"。这会让调试器直接执行 Python 文件，绕过 Flask CLI，所有基于命令行的功能（--reload、--debug、--app）全失效。
正确做法是强制走 Flask 官方启动流程：
-
"module": "flask"是唯一能激活 CLI 机制的配置项 - 如果用工厂函数（如
create_app()），"args"要写成["--app", "app:create_app", "run", "--no-reload"]，注意冒号分隔模块名和函数名 -
"--no-reload"必须加：Werkzeug fork 子进程后，VSCode 只 attach 主进程，断点会丢失 -
"--no-debugger"必须加：避免 Werkzeug 内建调试器和 VSCode 调试器端口冲突
.env 文件必须存在且路径/格式严格正确
VSCode 的调试器完全不读终端里 export FLASK_APP=app.py 这类命令，只认 envFile 指定的文件。路径错、空格多、编码乱码，都会导致 Could not locate a Flask application。
-
envFile必须设为"${workspaceFolder}/.env"，不能用相对路径（如./.env）或硬编码绝对路径 -
.env必须放在项目根目录，和app.py同级；内容严格两行，无空行、无前后空格：FLASK_APP=app.pyFLASK_DEBUG=1 - 若主文件在
src/app.py，则FLASK_APP要写成src.app，且项目必须用File → Open Folder打开整个文件夹（让src在sys.path中） -
FLASK_ENV在 Flask ≥2.3 已弃用，写进去反而可能报错
Python 解释器和虚拟环境必须手动激活并选对
VSCode 底部状态栏显示了 venv 路径 ≠ 终端已激活。没激活就 pip install flask，包实际装到了系统 Python 里，import flask 就会失败。
- Windows：运行
.\venv\Scripts\activate（注意是Scripts，不是Script） - macOS/Linux：运行
source venv/bin/activate - 激活成功后，终端提示符开头应有
(venv)；此时再运行python -c "import flask; print(flask.__version__)"验证 - 按
Ctrl+Shift+P输入Python: Select Interpreter，从列表中选你刚激活的那个环境（路径含venv、.venv或pyenv） - 选完后必须关掉旧终端、新开一个——VSCode 不自动继承激活状态
常见报错对应的真实原因和快速自查项
报错不是 Flask 代码问题，而是环境链断裂。以下现象可直接对照排查：
-
Could not locate a Flask application→.env文件不存在 / 路径不对 /FLASK_APP值写错（比如漏了.py后缀） -
socket.gaierror: [Errno 11001] getaddrinfo failed→"args"里--host写成了--host=0.0.0.0:5000（冒号不能跟在等号后面），应写成--host=0.0.0.0 --port=5000 - 断点灰色不可用 / 点击无反应 →
"justMyCode": true缺失，或"module": "flask"被误写成"module": "Flask"（大小写敏感） - 修改代码后服务静默退出 → 没加
--no-reload，Werkzeug fork 导致 VSCode 失去子进程控制
最易被忽略的是：项目必须用 File → Open Folder 打开整个文件夹，而不是双击打开单个 app.py —— 否则 sys.path 不含项目根目录，FLASK_APP=app.py 就永远找不到模块。
