launch.json必须通过VSCode齿轮图标自动生成，不可手写——手动易遗漏cwd、env、console等关键字段，导致断点失效、ModuleNotFoundError或“file not found”错误；正确做法是打开运行和调试侧边栏，点击⚙️选择Python模板，由VSCode生成带注释的完整配置。
launch.json 必须通过齿轮图标生成，不能手写
VSCode 的 launch.json 不是靠复制粘贴或手动拼 JSON 写出来的。手写极易漏掉 cwd、env、console 等关键字段，导致断点不触发、ModuleNotFoundError 或直接报 “file not found”。
正确做法是：打开「运行和调试」侧边栏（Ctrl+Shift+D / Cmd+Shift+D），点击顶部 ⚙️ 图标，选择「Python」→「Python File」模板。VSCode 会自动生成带完整注释的配置，字段语义明确，且自动适配当前已安装的 Python 扩展。
如果没看到 Python 选项，说明：
- 官方 Python 扩展（ms-python.python）未安装或被禁用
- 当前工作区没打开任何 .py 文件，VSCode 无法识别语言上下文
- 已安装的是 Pylance，但没装 Python 主扩展（仅装 Pylance 不足以启用调试）
program 和 module 字段不能混用，选错就找不到入口
launch.json 里真正决定启动方式的是 "request": "launch" 下的两个互斥字段：program（运行脚本文件）或 module（以模块方式导入）。填了 program 还加 module，VSCode 会忽略后者，但逻辑已混乱。
常见错误场景：
立即学习“Python免费学习笔记（深入）”；
- 想调试
src/main.py，却用了"module": "src.main"→ 报No module named 'src.main'，因为没执行pip install -e . - 想跑
python -m httpx，却写了"program": "httpx"→ 报FileNotFoundError，因为这不是文件路径 - 用
program时写相对路径如"./scripts/run.py"，但没设"cwd": "${workspaceFolder}"→ 导入失败，sys.path不含项目根目录
实操建议：
- 脚本式启动（如单文件工具、CLI 入口）→ 用 program，路径写 "${workspaceFolder}/main.py"
- 包结构项目（如 myapp/__main__.py）→ 用 module，值写 "myapp"，并确保该包已安装为可编辑模式
type 字段必须是小写的 "python"，大小写敏感
launch.json 中 "type" 字段决定 VSCode 启用哪个调试器。写成 "Python"、"PYTHON" 或 "node"（比如从其他项目复制配置时没改）——断点完全不生效，控制台也不会打印 Python 启动日志，只显示“调试已结束”。
必须确认：
- "type": "python"（全小写）
- 已安装官方 ms-python.python 扩展
- VSCode 右下角状态栏显示的 Python 解释器路径，与你在终端中运行 which python（macOS/Linux）或 where python（Windows）的结果一致
- Windows 用户注意路径分隔符：用正斜杠 / 或双反斜杠 \，单反斜杠 会导致 JSON 解析失败
固定调试某个文件时，program 要用 ${workspaceFolder} 变量
默认配置里 "program": "${file}" 表示每次调试当前打开的文件，不适合项目级调试。要固定运行 main.py 或 src/app.py，就得把 program 改成带变量的路径。
推荐写法：
- "program": "${workspaceFolder}/main.py"（项目根目录下的文件）
- "program": "${workspaceFolder}/src/app.py"（子目录文件）
- 避免硬编码绝对路径（如 "C:/project/main.py"），否则换机器或换用户就失效
额外提醒：
- 如果项目依赖 src/ 目录结构或使用 pyproject.toml，还需确认当前解释器已执行 pip install -e .
- 修改 launch.json 后，必须重启调试会话（停止再 F5），旧配置不会热更新
- justMyCode 默认为 true，调试时跳过标准库和第三方包；若需进 requests 或 httpx 源码，得设为 false，但会显著拖慢调试速度
调试配置最易被忽略的点，其实是 cwd 和解释器路径的耦合关系：哪怕 program 路径写对了，cwd 错了，import 就可能失败；而解释器路径选错了，连 launch.json 里写的 module 名都解析不了。这两处不匹配，比语法错误更难排查。
