VSCode C/C++调试配置文件 launch.json 全字段解析

launch.json 是 Visual Studio Code 中配置调试器的核心文件，用于定义调试会话的启动参数和行为。以下是对其字段的深度解析：

基础结构

launch.json 必须包含一个 configurations 数组，每个数组元素代表一个独立的调试配置。示例框架：

{
  "version": "0.2.0",
  "configurations": [
    {
      // 调试配置字段
    }
  ]
}

---

核心字段详解

name

调试配置的名称，显示在调试启动下拉列表中。建议使用明确标识用途的命名：

"name": "(gdb) Launch Program"

type

指定调试器类型。C/C++ 开发常用：

"type": "cppdbg"  // 使用 GDB/LLDB 调试器

request

定义调试会话的启动方式：

• launch：启动新进程并附加调试器
• attach：附加到已运行的进程

"request": "launch"

program

指定待调试的可执行文件路径。支持变量替换（如 ${workspaceFolder}）：

"program": "${workspaceFolder}/build/myapp"

args

传递给程序的命令行参数数组：

"args": ["--input", "data.txt", "--verbose"]

stopAtEntry

是否在程序入口点自动暂停：

"stopAtEntry": true

---

高级调试配置

cwd

设置工作目录（影响文件路径解析）：

"cwd": "${workspaceFolder}/data"

environment

添加环境变量：

"environment": [
  {"name": "DEBUG_MODE", "value": "1"},
  {"name": "PATH", "value": "/custom/bin:${env:PATH}"}
]

externalConsole

控制是否使用外部终端窗口：

"externalConsole": false  // 使用 VSCode 集成终端

MIMode

指定调试器类型（需与 type 配合）：

"MIMode": "gdb"  // 或 "lldb"

---

调试器路径配置

miDebuggerPath

指定 GDB/LLDB 调试器的完整路径：

"miDebuggerPath": "/usr/local/bin/gdb"

miDebuggerServerAddress

远程调试时指定调试服务器地址：

"miDebuggerServerAddress": "192.168.1.100:2000"

---

预处理配置

preLaunchTask

调试前执行的构建任务（需在 tasks.json 中定义）：

"preLaunchTask": "build-myapp"

setupCommands

初始化调试器时执行的命令（适用于高级调试场景）：

"setupCommands": [
  {
    "description": "启用漂亮打印",
    "text": "-enable-pretty-printing",
    "ignoreFailures": true
  }
]

---

源码映射配置

sourceFileMap

将调试器看到的文件路径映射到本地路径（适用于远程调试）：

"sourceFileMap": {
  "/remote/path": "${workspaceFolder}/local"
}

additionalSOLibSearchPath

指定额外共享库搜索路径：

"additionalSOLibSearchPath": "/opt/custom_libs"

---

多进程调试配置

processId

附加到特定进程 ID（需配合 request: "attach"）：

"processId": "12345"

filterProcesses

通过名称过滤目标进程：

"filterProcesses": ["myapp*"]

---

集成终端控制

console

精细控制终端类型：

"console": "integratedTerminal"  // 可选：externalTerminal, internalConsole

internalConsoleOptions

控制内部调试控制台行为：

"internalConsoleOptions": "openOnSessionStart"

---

完整配置示例

结合常用功能的典型配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "(gdb) Debug Project",
      "type": "cppdbg",
      "request": "launch",
      "program": "${workspaceFolder}/build/app",
      "args": ["--config=debug.cfg"],
      "stopAtEntry": false,
      "cwd": "${workspaceFolder}",
      "environment": [{"name": "LD_LIBRARY_PATH", "value": "/custom/libs"}],
      "externalConsole": false,
      "MIMode": "gdb",
      "miDebuggerPath": "/usr/bin/gdb",
      "setupCommands": [
        {"text": "handle SIGPIPE nostop noprint pass"}
      ],
      "preLaunchTask": "cmake-build",
      "sourceFileMap": {
        "/mnt/remote": "${workspaceFolder}"
      }
    }
  ]
}