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) # 生成调试符号 [1,4](@ref)
# 可选：进一步指定编译标志
set(CMAKE_CXX_FLAGS_DEBUG "$ENV{CXXFLAGS} -O0 -Wall -g -ggdb") # -O0 优化级别便于调试，-g 生成调试信息 [1,2](@ref)

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 创建调试配置文件

在 VSCode 中打开项目文件夹。
切换到"运行和调试"视图 (Ctrl+Shift+D)。
点击"创建 launch.json 文件"，选择 C++ (GDB/LLDB) 。
这将自动生成 .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 中的任务标签
        }
    ]
}

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

复制代码

{
    "version": "2.0.0",
    "options": {
        "cwd": "${workspaceFolder}/build" // 任务在 build 目录下执行
    },
    "tasks": [
        {
            "label": "cmake-build", // 此标签必须与 preLaunchTask 一致
            "type": "shell",
            "command": "bash",
            "args": [
                "-c",
                "cmake -DCMAKE_BUILD_TYPE=Debug .. && make -j4" // 配置和编译命令
            ],
            "group": "build",
            "presentation": {
                "echo": true,
                "reveal": "always"
            }
        }
    ]
}

4. 开始调试

设置断点：在代码编辑器的行号左侧点击，设置断点（红色圆点）。
启动调试 ：按 F5 键。如果配置了 preLaunchTask，VSCode 会先自动编译项目，然后程序运行并在断点处暂停。
调试控制 ：
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（退出）