VS Code `launch.json` 完整配置指南：参数详解 + 配置实例

原创已于 2025-07-14 01:25:09 修改 · 2.3k 阅读

36 ·

CC 4.0 BY-SA版权

文章标签：

#json #debug #vscode #launch.json #调试配置 #调试 #python

于 2025-07-14 01:24:41 首次发布

文章目录

在使用 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`

步骤如下：

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

🧠 八、小贴士

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