Ubuntu 下使用 VSCode 调试 C++ CMake 项目指南

1. 环境准备

确保您的系统已安装必要的编译工具链、调试器和 VSCode 插件。

组件类别	具体项目	安装/配置说明
系统工具	编译工具链 (build-essential)	终端执行：sudo apt update && sudo apt install build-essential gdb cmake
	调试器 (GDB)	通常已包含在 build-essential 中，也可单独安装
VSCode 插件	C/C++ (Microsoft)	提供代码智能感知、调试支持
	CMake 与 CMake Tools	增强对 CMake 项目的支持（非必需但推荐）

2. 项目配置（CMakeLists.txt）

在项目的 CMakeLists.txt 中，必须设置 Debug 构建类型以生成包含调试信息的可执行文件。这是能够进行断点调试的基础

cmake_minimum_required(VERSION 3.10) project(MyProject)
# 关键配置：设置为 Debug 模式
set(CMAKE_BUILD_TYPE Debug)
# 生成调试符号
# 可选：进一步指定编译标志
set(CMAKE_CXX_FLAGS_DEBUG "$ENV{CXXFLAGS} -O0 -Wall -g -ggdb")
# -O0 优化级别便于调试，-g 生成调试信息
add_executable(${PROJECT_NAME} main.cpp)

使用标准的 CMake 流程构建项目：

mkdir -p build
cd build
cmake ..
make -j4

3. 配置 VSCode 调试环境

VSCode 主要通过当前项目根目录下 .vscode 文件夹中的 launch.json 和 tasks.json 文件来控制调试行为。

3.1 创建调试配置文件

1. 在 VSCode 中打开项目文件夹。
2. 切换到'运行和调试'视图 (Ctrl+Shift+D)。
3. 点击'创建 launch.json 文件'，选择 C++ (GDB/LLDB)。
4. 这将自动生成 .vscode/launch.json 文件。根据需要，可能还会自动生成或需要手动创建 tasks.json 文件

3.2 关键配置详解

下面表格列出了 launch.json 和 tasks.json 中最关键的配置项及其作用。

配置文件	配置项	说明与示例
launch.json	"program"	【最关键】 指定要调试的可执行文件的绝对路径。例如：${workspaceFolder}/build/MyProject
	"preLaunchTask"	指定在调试开始前自动执行的任务的 label，通常用于编译项目。例如："cmake-build"
	"args"	传递给程序的命令行参数，以 JSON 数组格式书写。例如：["-arg1", "value1"]
	"cwd"	程序启动时的工作目录。例如：${workspaceFolder} 或 ${workspaceFolder}/bin
	"environment"	设置程序运行时的环境变量，对于指定库路径（LD_LIBRARY_PATH）非常有用
	"MIMode"	指定调试器类型，在 Linux 上通常是 "gdb"
tasks.json	"label"	任务的唯一标识符，必须与 launch.json 中的 preLaunchTask 值一致
	"command", "args"	定义具体执行的编译命令和参数。例如，使用 cmake 和 make

一个集成了自动化构建任务的 launch.json 配置示例如下：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "(gdb) Launch - MyProject",
      "type": "cppdbg",
      "request": "launch",
      "program": "${workspaceFolder}/build/MyProject",
      "args": [],
      "stopAtEntry": false,
      "cwd": "${workspaceFolder}",
      "environment": [{"name": "LD_LIBRARY_PATH", "value": "/your/lib/path"}],
      "externalConsole": false,
      "MIMode": "gdb",
      "setupCommands": [
        {
          "description": "为 gdb 启用整齐打印",
          "text": "-enable-pretty-printing",
          "ignoreFailures": true
        }
      ],
      "preLaunchTask": "cmake-build"
    }
  ]
}

对应的 tasks.json 文件示例，用于定义调试前的编译任务：

{
  "version": "2.0.0",
  "options": {
    "cwd": "${workspaceFolder}/build"
  },
  "tasks": [
    {
      "label": "cmake-build",
      "type": "shell",
      "command": "bash",
      "args": ["-c", "cmake -DCMAKE_BUILD_TYPE=Debug .. && make -j4"],
      "group": "build",
      "presentation": {
        "echo": true,
        "reveal": "always"
      }
    }
  ]
}

4. 开始调试

1. 设置断点：在代码编辑器的行号左侧点击，设置断点（红色圆点）。
2. 启动调试：按 F5 键。如果配置了 preLaunchTask，VSCode 会先自动编译项目，然后程序运行并在断点处暂停。
3. 调试控制：
   1. F10 (单步跳过)：执行当前行，不进入函数内部。
   2. F11 (单步执行)：执行当前行，如该行是函数调用，则进入函数内部。
   3. Shift+F11 (单步跳出)：执行完当前函数剩余代码，返回到调用处。
   4. F5 (继续)：从当前断点运行至下一个断点。
   5. Shift+F5 (停止调试)。
   6. 在 VARIABLES(变量) 窗口查看或 Watch(监视) 窗口添加表达式来监视变量值

5. 常见问题与解决方案

问题现象	可能原因与解决方案
调试时提示'无法找到可执行文件'	launch.json 中的 program 路径错误。检查可执行文件是否在指定路径，文件名是否正确
断点不被命中（显示灰色）	程序未包含调试信息。确保 CMake 以 Debug 模式编译（-DCMAKE_BUILD_TYPE=Debug）
程序启动后立即退出，退出代码为 127	通常表示缺少动态链接库。确保 LD_LIBRARY_PATH 环境变量在 launch.json 的 environment 字段中正确设置，或者使用 ldd 命令检查可执行文件的依赖库
'preLaunchTask 未找到'错误	tasks.json 中任务的 label 与 launch.json 中的 preLaunchTask 名称不匹配。确保两者完全一致

6. 补充技巧

使用 CMake Tools 扩展：安装 CMake Tools 扩展后，它可以简化 CMake 项目的配置、构建和调试目标选择过程，有时可以避免手动编写 tasks.json

直接使用 GDB 命令行调试：对于快速验证或复杂问题，可以直接在终端中使用 GDB。使用 -g 选项编译程序后，通过命令 gdb /path/to/your/program 启动调试。常用命令有 break（设断点）、run（运行）、next、step、print（打印变量）、backtrace（查看调用栈）和 quit（退出）