Linux 下用 VS Code 高效调试（二）

目录

1.settings.json

2.核心配置项总览（按功能分类）

2.1.基础路径与生成器配置

2.2.配置过程控制

2.3.构建与编译配置

2.4.工具链与编译器配置

2.5.调试与运行配置

2.6.环境变量配置

[2.7.测试与 CTest 配置](#2.7.测试与 CTest 配置)

[2.8.CPack 配置](#2.8.CPack 配置)

[2.9.CMake Presets 配置](#2.9.CMake Presets 配置)

2.10.日志与输出配置

2.11.高级与其他配置

3.变量替换系统详解

4.常用配置示例

5.完整的settings.json

---

1.settings.json

VSCode 中 CMake 工程的编译调试配置主要通过CMake Tools 插件 的settings.json配置项实现。官方文档：

https://github.com/microsoft/vscode-cmake-tools/blob/main/docs/cmake-settings.md

2.核心配置项总览（按功能分类）

2.1.基础路径与生成器配置

配置项	描述	默认值	支持变量替换
cmake.cmakePath	指定 CMake 可执行文件路径	cmake（自动搜索 PATH）	是（支持${workspaceFolder}等）
cmake.generator	设置 CMake 生成器（如 "Ninja"、"Unix Makefiles"）	null（自动选择）	否
cmake.buildDirectory	构建目录路径（CMakeCache.txt 所在位置）	${workspaceFolder}/build	是
cmake.sourceDirectory	CMakeLists.txt 根目录	${workspaceFolder}	是
cmake.installPrefix	设置CMAKE_INSTALL_PREFIX	null	是

2.2.配置过程控制

配置项	描述	默认值	支持变量替换
cmake.configureOnOpen	打开项目时自动配置	true	否
cmake.configureOnEdit	保存 CMakeLists.txt 时自动重新配置	true	否
cmake.automaticReconfigure	切换工具链或预设时自动重新配置	true	否
cmake.configureArgs	CMake 配置阶段的额外参数（不建议用于-D参数）	[]	是
cmake.configureSettings	传递给 CMake 的-D参数键值对（推荐）	{}	是
cmake.cacheInit	缓存初始化文件路径（通过-C参数传递）	[]	否
cmake.deleteBuildDirOnCleanConfigure	清洁配置时删除构建目录	false	否
cmake.skipConfigureIfCachePresent	存在 CMake 缓存时跳过配置	null	否

2.3.构建与编译配置

配置项	描述	默认值	支持变量替换
cmake.buildBeforeRun	运行 / 调试前自动构建目标	true	否
cmake.buildArgs	传递给cmake --build的额外参数	[]	是
cmake.buildToolArgs	传递给底层构建工具的额外参数	[]	是
cmake.parallelJobs	并行构建任务数（0 = 自动检测 CPU 核心数）	0	否
cmake.clearOutputBeforeBuild	构建前清空输出	true	否
cmake.buildTask	生成 VSCode 构建任务	false	否
cmake.exportCompileCommandsFile	生成 compile_commands.json	true	否
cmake.copyCompileCommands	配置成功后复制 compile_commands.json 到指定路径	null	是
cmake.additionalBuildProblemMatchers	自定义构建问题匹配器	[]	否

2.4.工具链与编译器配置

配置项	描述	默认值	支持变量替换
cmake.additionalCompilerSearchDirs	额外编译器搜索路径（如 MinGW 安装目录）	[]	否
cmake.additionalKits	自定义工具链文件路径	[]	否
cmake.enableAutomaticKitScan	启用自动工具链扫描	true	否
cmake.showSystemKits	在工具链选择中显示系统工具链	true	否
cmake.ignoreKitEnv	忽略工具链环境变量	false	否
cmake.toolset	设置 CMake 工具集	null	否
cmake.platform	设置 CMake 平台	null	否
cmake.emscriptenSearchDirs	Emscripten 搜索路径	[]	否

2.5.调试与运行配置

配置项	描述	默认值	支持变量替换
cmake.debugConfig	调试配置（可自定义调试适配器）	null	是
cmake.launchBehavior	启动目标时的终端行为	reuseTerminal	否
cmake.setBuildTargetSameAsLaunchTarget	设置启动目标时自动同步构建目标	false	否
cmake.saveBeforeBuild	构建前保存所有打开文档	true	否

2.6.环境变量配置

配置项	描述	默认值	支持变量替换
cmake.environment	配置、构建、测试时的全局环境变量	{}	是
cmake.buildEnvironment	仅构建时的环境变量	null	是
cmake.configureEnvironment	仅配置时的环境变量	null	是
cmake.testEnvironment	仅测试 / 调试时的环境变量	{}	是
cmake.cpackEnvironment	仅运行 cpack 时的环境变量	{}	是

2.7.测试与 CTest 配置

配置项	描述	默认值	支持变量替换
cmake.ctestArgs	传递给 CTest 的额外参数	[]	是
cmake.ctestDefaultArgs	CTest 默认参数	["-T", "test", "--output-on-failure"]	否
cmake.ctest.parallelJobs	CTest 并行测试任务数	0	否
cmake.ctest.allowParallelJobs	允许 CTest 并行运行测试	false	否
cmake.ctest.testExplorerIntegrationEnabled	启用测试资源管理器集成	true	否
cmake.ctest.debugLaunchTarget	CTest 调试目标	null	否
cmake.ctest.testSuiteDelimiter	测试套件名称分隔符	null	否
cmake.coverageInfoFiles	LCOV 覆盖率信息文件	[]	是
cmake.preRunCoverageTarget	覆盖率测试前构建目标	null	否
cmake.postRunCoverageTarget	覆盖率测试后构建目标	null	否

2.8.CPack 配置

配置项	描述	默认值	支持变量替换
cmake.cpackArgs	传递给 cpack 的额外参数	[]	是
cmake.cpackPath	cpack 可执行文件路径	null	否

2.9.CMake Presets 配置

配置项	描述	默认值	支持变量替换
cmake.useCMakePresets	控制何时使用 CMake Presets	auto	否
cmake.allowCommentsInPresetsFile	允许 Presets 文件中使用注释	false	否
cmake.allowUnsupportedPresetsVersions	允许使用不支持的 Presets 版本	false	否

2.10.日志与输出配置

配置项	描述	默认值	支持变量替换
cmake.loggingLevel	日志输出级别（trace/debug/info/...）	"info"	否
cmake.revealLog	何时显示输出日志	"always"	否
cmake.enabledOutputParsers	启用的输出解析器	["cmake", "gcc", "gnuld", "msvc", "ghs", "diab", "iwyu"]	否
cmake.outputLogEncoding	工具输出编码	"auto"	否
cmake.parseBuildDiagnostics	解析编译器输出中的诊断信息	true	否

2.11.高级与其他配置

配置项	描述	默认值	支持变量替换
cmake.cmakeCommunicationMode	扩展与 CMake 通信协议	"automatic"	否
cmake.enableLanguageServices	启用 CMake 语言服务	true	否
cmake.enableTraceLogging	启用跟踪日志	false	否
cmake.exclude	忽略的文件夹列表	[]	否
cmake.ignoreCMakeListsMissing	忽略缺少 CMakeLists.txt 的错误	false	否
cmake.loadCompileCommands	读取 compile_commands.json 启用单文件编译	true	否
cmake.mergedCompileCommands	合并 compile_commands.json 的路径	null	否
cmake.mingwSearchDirs	已弃用 ，使用additionalCompilerSearchDirs	[]	否
cmake.options.advanced	CMake Tools 高级选项	See package.json	否
cmake.options.statusBarVisibility	状态栏可见性	"hidden"	否
cmake.pinnedCommands	固定到命令面板的命令	["workbench.action.tasks.configureTaskRunner", "workbench.action.tasks.runTask"]	否
cmake.shell	用于子进程调用的 shell 路径	null	否
cmake.touchbar.visibility	触摸栏可见性（macOS）	"default"	否
cmake.touchbar.advanced	触摸栏高级选项	See package.json	否
cmake.useVsDeveloperEnvironment	控制是否使用 VS 开发环境	"auto"	否
cmake.autoSelectActiveFolder	自动选择活动文件夹（多根工作区）	true	否
cmake.defaultActiveFolder	默认活动文件夹名称	""	否
cmake.defaultVariants	覆盖默认变体集	See package.json	否

3.变量替换系统详解

配置中可使用${variable}语法替换特殊值，支持以下类型：

1.内置变量

变量	描述
${workspaceFolder}	工作区根目录路径
${sourceDirectory}	CMakeLists.txt 根目录路径
${buildDirectory}	构建目录路径
${buildType}	当前构建类型（Debug/Release 等）
${buildKit}	当前工具链完整名称
${generator}	CMake 生成器名称
${userHome}	当前用户主目录

2.环境变量

• 语法：${env:VARNAME} 或 ${env.VARNAME}
• 示例：${env:PATH} 获取系统 PATH 环境变量

3.变体替换

• 语法：${variant:VARIANTNAME}
• 获取当前激活的变体选项值

4.命令替换（强大功能）

支持调用 CMake Tools 命令获取动态值，如：

命令	描述
${command:cmake.launchTargetPath}	获取启动目标完整路径（触发构建）
${command:cmake.getLaunchTargetPath}	获取启动目标完整路径（不触发构建）
${command:cmake.activeConfigurePresetName}	获取当前激活的配置预设名称

5.测试调试占位符（launch.json 专用）

占位符	描述
${cmake.testProgram}	测试可执行文件完整路径
${cmake.testArgs}	测试命令行参数
${cmake.testWorkingDirectory}	测试工作目录

4.常用配置示例

{
  "cmake.generator": "Ninja",
  "cmake.buildDirectory": "${workspaceFolder}/build/${buildType}",
  "cmake.configureSettings": {
    "CMAKE_BUILD_TYPE": "Debug",
    "CMAKE_CXX_STANDARD": 20,
    "CMAKE_INSTALL_PREFIX": "${workspaceFolder}/install"
  },
  "cmake.parallelJobs": 8,
  "cmake.buildArgs": ["--verbose"],
  "cmake.debugConfig": {
    "args": ["--debug"],
    "stopAtEntry": false
  },
  "cmake.environment": {
    "CC": "gcc-11",
    "CXX": "g++-11"
  }
}

5.完整的settings.json

通用、开箱即用、跨 Windows/Linux 都能跑 的 VSCode .vscode/settings.json CMake 完整配置。功能有：

• 自动区分 Debug/Release 构建目录
• 自动生成 compile_commands.json（给 clangd / 代码提示用）
• 8 线程并行编译
• 自带调试参数、环境变量、编译器标准
• 适配 GCC / MinGW / MSVC / Ninja
• 注释齐全，直接复制就能用

{
    // ===================== CMake 核心配置 =====================
    // CMake 可执行文件路径（自动从 PATH 查找，一般不用改）
    "cmake.cmakePath": "cmake",

    // 构建目录：按构建类型分开，避免 Debug/Release 混在一起
    "cmake.buildDirectory": "${workspaceFolder}/build/${buildType}",

    // CMake 源码根目录（默认工作区根目录）
    "cmake.sourceDirectory": "${workspaceFolder}",

    // 生成器：优先 Ninja（更快），Windows 自动用 VS，Linux 用 Make
    "cmake.generator": "Ninja",

    // 安装路径（make install 时的目标目录）
    "cmake.installPrefix": "${workspaceFolder}/output",

    // ===================== 构建行为 =====================
    // 打开项目时自动执行 cmake configure
    "cmake.configureOnOpen": true,

    // 修改 CMakeLists.txt 后自动重新配置
    "cmake.configureOnEdit": true,

    // 调试/运行前自动构建
    "cmake.buildBeforeRun": true,

    // 并行编译线程数（0=自动，建议设为 CPU 核心数）
    "cmake.parallelJobs": 8,

    // 构建前清空输出面板
    "cmake.clearOutputBeforeBuild": true,

    // 构建时显示详细命令（--verbose）
    "cmake.buildArgs": ["--verbose"],

    // ===================== CMake 缓存参数（-Dxxx=yyy） =====================
    "cmake.configureSettings": {
        // 构建类型（会被 CMake Tools 变体自动覆盖，这里仅兜底）
        "CMAKE_BUILD_TYPE": "${buildType}",

        // C++ 标准：按需改成 17 / 20 / 23
        "CMAKE_CXX_STANDARD": 17,
        "CMAKE_CXX_STANDARD_REQUIRED": "ON",

        // 导出 compile_commands.json（clangd / 代码补全必备）
        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",

        // 禁用 CMake 自带冗余警告
        "CMAKE_CXX_FLAGS": "-Wall -Wextra -O0",
        "CMAKE_CXX_FLAGS_DEBUG": "-g",
        "CMAKE_CXX_FLAGS_RELEASE": "-O2 -DNDEBUG"
    },

    // ===================== compile_commands 自动复制 =====================
    // 生成后复制到项目根目录，clangd 直接识别
    "cmake.copyCompileCommands": "${workspaceFolder}/compile_commands.json",

    // ===================== 调试默认配置 =====================
    "cmake.debugConfig": {
        // 程序启动参数（按需修改）
        "args": [],
        // 工作目录
        "cwd": "${workspaceFolder}",
        // 是否在入口暂停
        "stopAtEntry": false,
        // 外部终端运行（Windows 建议 true，Linux 可选）
        "externalConsole": false
    },

    // ===================== 环境变量 =====================
    // 全局环境变量（配置/构建/调试都生效）
    "cmake.environment": {
        // "PATH": "${env:PATH};C:/your/custom/path"
    },

    // ===================== 日志与输出 =====================
    "cmake.loggingLevel": "info",
    "cmake.revealLog": "always",

    // ===================== 其他优化 =====================
    // 构建后自动刷新问题面板
    "cmake.parseBuildDiagnostics": true,

    // 多工作区时自动选择当前活动目录
    "cmake.autoSelectActiveFolder": true,

    // 状态栏显示 CMake 常用快捷入口
    "cmake.options.statusBarVisibility": "visible"
}