必须用 CMakePresets.json 统一团队构建配置，因其支持继承、条件分支、多平台适配，且被主流 IDE 原生识别；需置于项目根目录，preset 名全局唯一，布尔值写 true/false，避免缓存污染与变量误用。
用 CMakePresets.json 统一 C++ 团队构建配置，不是“能不能”，而是“必须做”——否则每人本地 cmake -S . -B build -G "Ninja" -DCMAKE_BUILD_TYPE=RelWithDebInfo 打一遍，参数不一致、路径不一致、工具链漏配，CI 和本地构建就不是同一套逻辑。
为什么不用命令行参数而用 Presets？
命令行参数难复用、难版本控制、难共享。团队里有人加了 -DENABLE_TESTS=ON，有人忘了加 -DCMAKE_TOOLCHAIN_FILE，有人在 Windows 用 Visual Studio 生成器，CI 却跑 Ninja —— 这些差异全靠口头同步，迟早出问题。
Presets 把构建意图固化为 JSON，支持继承、条件分支、多平台适配，且被 VS Code、CLion、VS 2022 原生识别，IDE 直接读取并提供下拉选择。
关键点：
立即学习“C++免费学习笔记（深入）”；
-
CMakePresets.json必须放在项目根目录（和CMakeLists.txt同级） - 所有 preset 名称（
name）全局唯一，推荐按用途+平台命名，如build-ninja-linux-debug - 不要手动写
cacheVariables里的布尔值为"ON"字符串——CMake 会当字符串处理，应写true或false（JSON 布尔）
一个可落地的跨平台基础 preset 示例
以下是一个最小但实用的 CMakePresets.json，覆盖 Linux/macOS/Windows 主流场景，不含冗余字段，开箱即用：
{
"version": 6,
"configurePresets": [
{
"name": "base",
"displayName": "Base configuration",
"description": "Shared settings for all builds",
"binaryDir": "${sourceDir}/build/${presetName}",
"cacheVariables": {
"CMAKE_CXX_STANDARD": "20",
"CMAKE_CXX_STANDARD_REQUIRED": true,
"CMAKE_EXPORT_COMPILE_COMMANDS": true
}
},
{
"name": "build-ninja-debug",
"displayName": "Debug (Ninja)",
"inherits": ["base"],
"generator": "Ninja",
"cacheVariables": {
"CMAKE_BUILD_TYPE": "Debug"
},
"condition": {
"type": "equals",
"lhs": "${hostSystemName}",
"rhs": "Linux"
}
},
{
"name": "build-ninja-debug-win",
"displayName": "Debug (Ninja, Windows)",
"inherits": ["base"],
"generator": "Ninja",
"cacheVariables": {
"CMAKE_BUILD_TYPE": "Debug"
},
"condition": {
"type": "equals",
"lhs": "${hostSystemName}",
"rhs": "Windows"
}
}
]
}
说明：
-
version: 6是当前（CMake 3.25+）推荐版本，兼容性好；用version: 4会缺失condition支持 -
inherits不是“继承类”，而是“复用字段”，子 preset 可覆盖父 preset 的任意字段（如cacheVariables中同名键会被替换） -
${hostSystemName}是内置变量，值为Linux/Windows/Darwin，比手写if(WIN32)更可靠 - Windows 下若需 MSVC 工具链，把
generator换成"Visual Studio 17 2022"，并加"architecture": "x64"字段
常见错误与绕过方式
实际落地时，90% 的问题出在变量展开或路径拼接上：
-
"binaryDir": "${sourceDir}/build"→ 错误：没带${presetName}，多个 preset 共用同一 build 目录，缓存污染 -
"cacheVariables": { "BUILD_SHARED_LIBS": "ON" }→ 错误：“ON” 是字符串，CMake 不识别为布尔真，应写true -
"condition": { "type": "equals", "lhs": "${hostSystemName}", "rhs": "win32" }→ 错误：win32小写，实际值是Windows（首字母大写） - VS Code 不识别 preset？检查是否安装了官方 “CMake Tools” 插件，并确认工作区打开的是项目根目录（不是子文件夹）
- 执行
cmake --list-presets报错 “No presets found”？确认文件名是CMakePresets.json（不是cmake-presets.json或CMakePresets.yml）
团队协作的关键细节
统一配置不等于“一刀切”。真正难的是让 preset 既稳定又可扩展：
- 把敏感配置（如私有 toolchain 路径、密钥开关）抽到
user-presets.json（Git 忽略），用include引入，避免提交硬编码路径 - CI 脚本中显式指定 preset：
cmake --preset build-ninja-release-linux，禁止再用裸cmake -B - 新增 preset 前，先在 PR 描述里贴出
cmake --preset xxx --dry-run输出，确认生成命令符合预期 - Windows 开发者若用 WSL，注意
${hostSystemName}返回的是Linux，不是Windows—— 这是正确行为，别强行 hack
最常被忽略的一点：Preset 不是“写完就扔”，它得随 CMakeLists.txt 的 project() 版本升级而同步更新。比如从 cmake_minimum_required(VERSION 3.20) 升到 3.25，就要检查 preset version 是否匹配，否则旧 CMake 会静默忽略整个文件。
