在使用 Visual Studio Code (VS Code) 进行代码调试时，launch.json 是一个非常关键的配置文件。它允许你定义多个调试任务，适用于不同的开发场景（如训练脚本、Jupyter Notebook、单元测试等）。

本文将全面解析 launch.json 的结构、字段含义、可选参数、变量使用以及常见配置示例。

---

📦 一、基本结构

{"version": "0.2.0","configurations": [{// 每个配置项}]
}

• "version"：表示该文件的格式版本（通常为 "0.2.0"）。
• "configurations"：是一个数组，包含多个调试配置对象，每个对象对应一个调试任务。

---

🔍 二、单个配置项详解

示例配置：

{"name": "Python: 调试训练脚本","type": "debugpy","request": "launch","program": "${file}","console": "integratedTerminal","justMyCode": false,"args": ["--epochs", "10","--batch-size", "32"],"env": {"CUDA_VISIBLE_DEVICES": "0"},"envFile": "${workspaceFolder}/.env","stopOnEntry": false,"subProcess": true,"cwd": "${workspaceFolder}","debugOptions": ["RedirectOutput"]
}

---

🧩 三、字段说明与可选值

字段名	类型	描述	可选值
"name"	string	显示在调试器中的名称	自定义
"type"	string	使用的调试器类型	"debugpy", "python", "pwa-node" 等
"request"	string	请求类型	"launch"（启动程序）、"attach"（附加到进程）
"program"	string	主程序入口路径（支持变量）	文件路径，如当前文件 ${file}，以及特定${workspaceFolder}/train.py
"console"	string	控制台输出方式	"integratedTerminal"、"none"、"internalConsole"
"justMyCode"	boolean	是否只调试用户代码	true、false
"args"	array	向程序传递的命令行参数	多个字符串组成的数组
"env"	object	设置环境变量	键值对形式
"envFile"	string	加载 .env 文件	文件路径
"stopOnEntry"	boolean	是否在入口暂停	true、false
"subProcess"	boolean	是否调试子进程	true、false
"cwd"	string	当前工作目录	文件路径
"module"	string	指定运行模块（替代 program）	如 "pytest"、"unittest"
"debugOptions"	array	特殊调试选项	"RedirectOutput"、"DjangoDebugging"、"Gevent" 等

---

📁 四、常用变量（宏替换）

VS Code 支持一些预定义变量，用于动态构建路径和内容：

变量名	含义
${workspaceFolder}	当前工作区根目录
${workspaceFolder:name}	多根项目中指定名称的根目录
${file}	当前打开的文件路径
${fileDir}	当前文件所在目录
${fileBasenameNoExtension}	当前文件名（不含扩展名）
${env:VAR_NAME}	获取系统环境变量，例如 ${env:HOME}

---

🛠️ 五、常见配置实例

1️⃣ 调试当前打开的 .py 文件

{"name": "Python: 调试当前文件","type": "python","request": "launch","program": "${file}","console": "integratedTerminal"
}

✅ 适用于快速调试任意 Python 文件，无需修改配置。

---

2️⃣ 调试 Jupyter Notebook

{"name": "Python: 调试Jupyter Notebook","type": "python","request": "launch","program": "${file}","console": "integratedTerminal","justMyCode": false
}

✅ 支持 .ipynb 文件调试（需安装 Jupyter 扩展）。

---

3️⃣ 调试 Pytest 测试用例

{"name": "Python: 调试测试用例","type": "python","request": "launch","module": "pytest","args": ["-v", "${file}"],"justMyCode": false
}

✅ 以调试模式运行 pytest 单元测试，支持断点调试。

---

4️⃣ 调试深度学习训练脚本（带 GPU 和环境变量）

{"name": "Python: 调试训练脚本","type": "debugpy","request": "launch","program": "${workspaceFolder}/train.py","console": "integratedTerminal","justMyCode": false,"args": ["--epochs", "10","--batch-size", "32"],"env": {"CUDA_VISIBLE_DEVICES": "0","PYTHONPATH": "${workspaceFolder}"},"envFile": "${workspaceFolder}/.env","subProcess": true,"cwd": "${workspaceFolder}"
}

✅ 适用于多进程、GPU 计算等复杂场景。

---

📝 六、.env 文件示例

如果你希望将敏感信息或大量环境变量放在外部文件中，可以创建 .env 文件：

CUDA_VISIBLE_DEVICES=0
PYTHONPATH=/home/user/project
API_KEY=my_secret_key

然后在 launch.json 中引用它：

"envFile": "${workspaceFolder}/.env"

---

🧪 七、如何创建和编辑 launch.json

步骤如下：

1. 打开你的项目文件夹。
2. 在 .vscode/ 目录下创建或编辑 launch.json。
3. 将上述配置复制进去，并根据你的实际路径、参数进行修改。
4. 在左侧点击“运行和调试”图标，选择对应的调试配置，点击绿色 ▶️ 开始调试。

---

🧠 八、小贴士

• 虚拟环境支持：确保 VS Code 使用了正确的 Python 解释器（右下角显示）。
• 路径变量：
  • ${workspaceFolder}：当前工作区根目录。
  • ${file}：当前打开的文件。
• 调试 Django 项目：启用 "DjangoDebugging" 可获得更好的兼容性。
• 多配置共存：你可以同时配置多个任务（如训练、测试、Jupyter 调试），方便切换。

---

📚 九、参考文献

• VS Code Debugging 官方文档
• Python 调试官方文档