必须先安装Python解释器（3.9+）再装VSCode Python扩展；调试需正确配置launch.json、解释器路径、PYTHONPATH及框架特设参数，否则易现断点失效、导入错误等问题。
安装Python解释器和VSCode Python扩展
VSCode本身不带Python运行时，必须先在系统中安装Python解释器（推荐 3.9+），再安装官方 Python 扩展（由 Microsoft 发布，ID 为 ms-python.python）。仅装扩展不装解释器，python 命令仍会报 command not found 或调试器启动失败。
- Windows 用户建议从 python.org 下载安装包，勾选
Add Python to PATH -
macOS 用户可用
brew install python，但注意brew安装的python实际是python3，VSCode 可能默认找不到，需在设置中手动指定路径（如/opt/homebrew/bin/python3） - Linux 用户确认
which python3输出有效路径，并在 VSCode 的python.defaultInterpreterPath中填入完整路径
配置 launch.json 启动调试
VSCode 调试依赖工作区根目录下的 .vscode/launch.json。首次点击「运行 → 启动调试」（或 Ctrl+Shift+D），若无该文件，会提示生成；选择环境为 Python File 即可自动生成基础模板。但默认配置常不适用真实项目结构。
- 调试单个脚本：保持
"module": "none"，确保"program"指向正确入口文件（如"${file}"表示当前打开文件） - 以模块方式运行（如
python -m mypackage.main）：设"module": "mypackage.main"，并删除"program"字段 - 需要传参时，在
"args"数组中写字符串，如["--verbose", "input.txt"]，不要合并成一个字符串 - 若项目含
venv，务必在launch.json中加"env": {"PYTHONPATH": "${workspaceFolder}"}，否则相对导入（from .utils import helper）会失败
解决断点不命中、ModuleNotFoundError 和路径问题
这类问题 80% 源于 VSCode 当前使用的 Python 解释器与终端不一致，或工作区根目录未设对。调试器不会自动继承 shell 的 PYTHONPATH 或激活的虚拟环境。
- 按
Ctrl+Shift+P输入Python: Select Interpreter，确认显示路径与你在终端中运行which python的结果一致 - 检查左下角状态栏是否显示正确的解释器路径；若显示
Python 3.x.x但没具体路径，说明未成功识别，需手动浏览定位 - 如果代码用
import src.utils报错，而src在工作区子目录中，应在launch.json的"env"中追加"PYTHONPATH": "${workspaceFolder}/src" - 使用 Poetry 或 Pipenv 时，不能只选解释器路径，还要在
launch.json中设"console": "integratedTerminal"并启用"justMyCode": false，否则调试器可能跳过虚拟环境中的包代码
调试 Flask/Django 等 Web 框架时的特殊设置
Web 应用默认监听 localhost:5000，但 VSCode 调试器若未附加到进程，修改代码后热重载会失效，甚至端口被占用导致启动失败。
立即学习“Python免费学习笔记（深入）”；
- Flask：在
launch.json中设"module": "flask"，"args": ["--no-debugger", "--no-reload", "run", "--port=5001"]，禁用 Flask 自带重载，让 VSCode 控制调试流程 - Django：用
"module": "django"，"args": ["runserver", "--noreload", "--verbosity=2"]；若模型迁移报错，需提前在终端运行python manage.py migrate - 两者都建议开启
"stopOnEntry": false，避免一启动就停在manage.py或app.py第一行 -
浏览器访问
http://localhost:5001触发断点时，确保请求未被缓存（可加时间戳参数或禁用浏览器缓存）
{
"version": "0.2.0",
"configurations": [
{
"name": "Python: Current File",
"type": "python",
"request": "launch",
"module": "none",
"program": "${file}",
"console": "integratedTerminal",
"env": {
"PYTHONPATH": "${workspaceFolder}"
},
"justMyCode": true
}
]
}
调试器对路径和环境变量极其敏感，哪怕多一个斜杠、少一个引号，都可能导致 ImportError 或静默失败。与其反复重启 VSCode，不如先在终端里跑通 python -m mymodule，再把对应参数平移进 launch.json。 
