所选模板会添加到 （若有）中 CMakePresets.json 。 否则，模板会复制到新的 文件中 CMakePresets.json 。

添加新的生成预设和测试预设

Visual Studio 2019 不会为新的生成预设和测试预设提供模板。 可直接编辑 来添加生成预设和测试预设 CMakePresets.json 。 有关详细信息，请参阅 “生成预设”列表 、 “测试预设”列表 或 示例 CMakePresets.json 文件 。

官方 CMake 文档 是有关编辑配置预设、生成预设和测试预设的最佳资源。 以下信息是与 Visual Studio 开发人员特别相关的 CMake 文档子集。

选择编译器

可以在“配置预设”中使用 cacheVariables.CMAKE_C_COMPILER 和 cacheVariables.CMAKE_CXX_COMPILER 设置 C 和 C++ 编译器。 这相当于通过命令行将 -D CMAKE_C_COMPILER=<value> 和 -D CMAKE_CXX_COMPILER=<value> 传递到 CMake。 有关详细信息，请参阅 CMAKE_<LANG>_COMPILER 。

使用以下示例，在 Visual Studio 中使用 cl.exe 和 clang-cl.exe 进行生成。 必须安装适用于 Windows 组件的 C++ Clang 工具，才能使用 clang-cl 进行生成。

使用 生成 cl.exe ：

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
  "CMAKE_C_COMPILER": "cl",
  "CMAKE_CXX_COMPILER": "cl"
使用  生成clang：
"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
  "CMAKE_C_COMPILER": "clang-cl",
  "CMAKE_CXX_COMPILER": "clang-cl"
"vendor": {
  "microsoft.com/VisualStudioSettings/CMake/1.0": {
    "intelliSenseMode": "windows-clang-x64"
如果使用 Visual Studio 16 2019 或 Visual Studio 17 2022 作为生成器，则可以使用 toolset 配置预设来指定 ClangCL 工具集：
"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
"toolset": "ClangCL",
"vendor": {
  "microsoft.com/VisualStudioSettings/CMake/1.0": {
    "intelliSenseMode": "windows-clang-x64"
有关支持 toolset 规范的生成器的详细信息，请参阅 CMake 文档中的 CMAKE_GENERATOR_TOOLSET。
在 Visual Studio 2019 中，当你使用 clang 或 clang-cl 进行生成时，必须显式指定 Clang IntelliSense 模式。
若要在 Visual Studio 之外重现这些生成，请参阅通过命令行或 CI 管道运行 CMake。
若要在 Linux 上或不使用 Visual C++ 工具集进行生成，请指定 PATH 实例上的编译器名称，或计算结果为编译器完整路径的环境变量。 不建议使用完整路径，以便文件可以共享。 使用 GCC 版本 8 生成的预设可能如下所示：
"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
  "CMAKE_C_COMPILER": "gcc-8",
  "CMAKE_CXX_COMPILER": "g++-8"
还可以使用 CMake 工具链文件设置编译器。 可使用 cacheVariables.CMAKE_TOOLCHAIN_FILE 设置工具链文件，这等效于从命令行将 -D CMAKE_TOOLCHAIN_FILE=<value> 传递到 CMake。 CMake 工具链文件最常用于交叉编译。 若要详细了解如何创作 CMake 工具链文件，请查看 CMake 工具链。
选择生成器
Windows 和 Linux 配置预设模板均将 Ninja 指定为默认生成器。 其他常见的生成器包括 Windows 上的 Visual Studio 生成器和 Linux 和 macOS 上的 Unix Makefile。 可以在配置预设中使用 generator 选项指定新的生成器。 这等效于从命令行将 -G 传递到 CMake。
在使用 Visual Studio 生成器进行生成时，将 architecture.strategy 和 toolset.strategy 设置为 set。 有关详细信息，请查看 CMake 生成器。
选择配置类型
可以使用 cacheVariables.CMAKE_BUILD_TYPE 为单个配置生成器设置配置类型（Debug 或 Release）。 这等效于从命令行将 -D CMAKE_BUILD_TYPE=<value> 传递到 CMake。 有关详细信息，请参阅 CMAKE_BUILD_TYPE。
在使用 Visual C++ 工具集进行生成时，选择目标体系结构和主机体系结构
可以使用 architecture.value 来设置目标体系结构（x64、Win32、ARM64 或 ARM）。 这等效于从命令行将 -A 传递到 CMake。 有关详细信息，请查看平台选择。
目前，Visual Studio 生成器要求使用 Win32 语法，而命令行生成器（如 Ninja）则要求使用在为 x86 生成时的 x86 语法。
可以使用 toolset.value 来设置主机体系结构（x64 或 x86）和工具集。 这等效于从命令行将 -T 传递到 CMake。 有关详细信息，请查看工具集选择。
architecture.strategy 和 toolset.strategy 值指示 CMake 如何处理体系结构和工具集字段。 set 表示 CMake 将设置相应的值，而 external 表示 CMake 将不会设置相应的值。
建议将 set 与 IDE 生成器（如 Visual Studio 生成器）配合使用。 将 external 与命令行生成器（如 Ninja）配合使用。 通过这些值，Visual Studio 等供应商可在调用 CMake 之前提供所需的环境。 若要详细了解体系结构和工具集字段，请参阅“配置预设”列表。
如果不想提供环境，则可以将 architecture.strategy 设置为 external，将 architecture.value 设置为 unspecified。 你可能会发现，对于以下任何一种原因，不提供环境都很有用：
你在使用 MSVC 以外的工具集。
你在使用自定义工具链，例如嵌入场景中。
你无需特定环境即可构建。
有关支持体系结构字段的 IDE 生成器的完整列表，请参阅 CMAKE_GENERATOR_PLATFORM。 有关支持工具集字段的 IDE 生成器的完整列表，请参阅 CMAKE_GENERATOR_TOOLSET。
使用下面的示例，在使用 Ninja 生成器时以 ARM64 为目标，或在使用 Visual Studio 16 2019 生成器时以 Win32 (x86) 为目标：
"generator": "Ninja",
"architecture": {
    "strategy": "external",
    "value": "arm64"
"generator": "Visual Studio 16 2019",
"architecture": {
    "strategy": "set",
     "value": "Win32"
设置和引用环境变量
可以使用环境映射来设置环境变量。 环境变量通过 inherits 字段继承，但你可根据需要进行替代。
预设的环境是其自身环境与其所有父级环境的联合。 如果多个 inherits 预设为同一变量提供了冲突的值，则首选 inherits 列表中较早的预设。 可以通过将变量设置为 null，来取消设置该继承自另一个预设的变量。
除非 inheritConfigureEnvironment 设置为 false，否则在“配置预设”中设置的环境变量也会自动流向关联的“生成预设”和“测试预设”。 有关详细信息，请参阅“配置预设”列表。
可以使用 $env{<variable-name>} 和 $penv{<variable-name>} 语法来引用环境变量。 有关详细信息，请查看宏扩展。
为交叉编译器配置 IntelliSense
默认情况下，Visual Studio 使用与指定的工具集和目标体系结构相匹配的 IntelliSense 模式。 若要进行交叉编译，则可能需要使用 Visual Studio 设置供应商映射中的 intelliSenseMode 选项来手动指定正确的 IntelliSense 模式。 有关详细信息，请查看 Visual Studio 设置供应商映射下的表中的 intelliSenseMode 条目。
在远程系统或适用于 Linux 的 Windows 子系统上进行配置和生成
借助 Visual Studio 中的  支持，你可以轻松地在 Windows、WSL 和远程系统上配置和生成项目CMakePresets.json。 在 Windows、远程系统或 WSL 上配置和生成项目的步骤是相同的。 然而，有一些行为是特定于远程开发的。
远程复制方案中的 ${sourceDir} 行为
在本地方案（包括 WSL1）中，${sourceDir} 的计算结果为在 Visual Studio 中打开的项目源目录的路径。 在远程复制方案中，${sourceDir} 的计算结果为“目标系统”上项目源目录的路径，而不是本地计算机上项目源目录的路径。
Visual Studio 远程设置供应商映射中的 sourceDir 值决定了“目标系统”上的项目源目录（默认为 $env{HOME}/.vs/$ms{projectDirName}）。 有关详细信息，请查看 Visual Studio 设置供应商映射下的表中的 sourceDir 条目。
远程输出的本地文件夹
如果 Visual Studio 远程设置供应商映射中的 copyBuildOutput 设置为 true，则远程复制方案需要一个本地目录来复制一些远程文件，如 CMake 文件 API 响应文件或生成文件。 这些文件将自动复制到 <local-source-directory>/out/<remote-connection-ID>/build/${presetName}。
在 Windows 和 WSL1 上调用相同的“配置预设”
如果尝试在 Windows 和 WSL1 上使用相同的配置预设，将会出现错误。 Windows 和 WSL1 都使用 Windows 文件系统，因此 CMake 会尝试对 Windows 和 WSL1 生成树使用相同的输出目录 (binaryDir)。
若要将相同的“配置预设”同时用于 Windows 和 WSL1 工具集，请创建另一个继承自原始预设的“配置预设”，并指定新的 binaryDir 值。 在以下示例中，windows-preset 可以在 Windows 上使用，base-preset 可以在 WSL1 上使用：
  "name": "windows-preset",
  "inherits": "base-preset",
  "binaryDir": "${sourceDir}/out/build/${presetName}",
  "vendor": {
    "microsoft.com/VisualStudioSettings/CMake/1.0": {
      "hostOS": "Windows"
在 Visual Studio 2019 中，仅支持 WSL1 工具集。 每当在 Windows 和 WSL 上调用 configure 时，都会看到这种行为。
启用 vcpkg 集成
Vcpkg 可帮助管理 Windows、Linux 和 macOS 上的 C 和 C++ 库。 必须将 vcpkg 工具链文件 (vcpkg.cmake) 传递到 CMake 才能启用 vcpkg 集成。 有关详细信息，请查看 vcpkg 文档。
启用  集成后，Visual Studio 不再自动将 vcpkg 工具链文件传递到 CMakeCMakePresets.json。 此更改消除了特定于 Visual Studio 的行为，并确保你可以通过命令行重现生成。
相反，可以使用  中的 VCPKG_ROOT 环境变量将路径设置为 vcpkg.cmakeCMakePresets.json：
"cacheVariables": {
   "CMAKE_TOOLCHAIN_FILE": {
      "value": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
       "type": "FILEPATH"
VCPKG_ROOT 应设置为 vcpkg 安装的根目录。 有关详细信息，请查看 vcpkg 环境变量。
如果你已经在使用 CMake 工具链文件，并且想要启用 vcpkg 集成，请参阅使用多个工具链文件。 按照这些说明操作，以通过使用 vcpkg 将外部工具链文件与项目结合使用。
launch.vs.json 和 tasks.vs.json 中的变量替换
 支持  和  中的变量替换CMakePresets.jsonlaunch.vs.jsontasks.vs.json。 下面是一些注意事项：
活动配置预设中设置的环境变量会自动流向  和  配置launch.vs.jsontasks.vs.json。 可将各个环境变量设置为 null 来取消设置  和  中的各个环境变量launch.vs.jsontasks.vs.json。 以下示例在  中将变量 DEBUG_LOGGING_LEVEL 设置为 null："env": { "DEBUG_LOGGING_LEVEL": null }launch.vs.json。
活动配置预设中设置的键值可通过语法 ${cmake.<KEY-NAME>} 在  和  中使用launch.vs.jsontasks.vs.json。 例如，使用 ${cmake.binaryDir} 引用活动配置预设的输出目录。
活动配置预设的环境映射中设置的各个环境变量可通过语法 ${env.<VARIABLE-NAME>} 在  和  中使用launch.vs.jsontasks.vs.json。
更新  和  文件以引用  语法而不是  语法launch.vs.jsontask.vs.jsonCMakePresets.jsonCMakeSettings.json。 当  作为活动配置文件时引用旧  语法的宏将在未来发布的版本中被弃用CMakeSettings.jsonCMakePresets.json。 例如，由于  使用 binaryDir 语法，可使用 ${cmake.binaryDir} 而不是 ${cmake.buildRoot} 来引用活动配置预设的输出目录CMakePresets.json。
如果没有按预期运行，则可以尝试一些故障排除步骤。
如果  或  无效，则 Visual Studio 会回退到其默认行为，并只显示默认配置预设CMakePresets.jsonCMakeUserPresets.json。 Visual Studio IntelliSense 可帮助你捕获其中许多 JSON 错误，但是它不知道你是使用错误名称通过 inherits 还是 configurePreset 引用了预设。
若要检查预设文件是否有效，请在项目的根目录下通过命令行运行 cmake --list-presets。 （需要 CMake 3.20 或更高版本。）如果其中一个文件无效，你将看到以下错误：
CMake Error: Could not read presets from
C:/Users/<user>/source/repos/<project-name>: JSON parse error
其他故障排除步骤包括：
删除缓存并重新配置项目（“CMake: 删除缓存”和“项目”>“配置 <project-name>”）。

关闭并重新打开 Visual Studio 中的文件夹（“文件”>“关闭文件夹”）。

删除项目根目录下的 .vs 文件夹。
如果发现了问题，则报告它的最佳方式是选择 Visual Studio 右上角的“发送反馈”按钮。

启用远程连接的日志记录
如果在将文件连接或复制到远程系统时遇到问题，可以为远程连接启用日志记录。 有关详细信息，请参阅远程连接的日志记录。
为 Windows 和 Linux 启用 AddressSanitizer
Visual Studio 支持 AddressSanitizer (ASAN)，这是一个适用于 Windows 和 Linux 开发的 C 和 C++ 运行时内存错误检测器。 CMakeSettings.json 中的 addressSanitizerEnabled 选项可启用 AddressSanitizer。  不支持此行为CMakePresets.json。
而是通过自行设置所需的编译器和链接器标志来启用和禁用 AddressSanitizer。 如果设置它们，则会删除 Visual Studio 特定的行为，并确保相同的  文件可从命令行重现你的生成CMakePresets.json。
可以将下面的示例添加到  中，为目标启用或禁用 AddressSanitizerCMakeLists.txt：
option(ASAN_ENABLED "Build this target with AddressSanitizer" ON)
if(ASAN_ENABLED)
  if(MSVC)
    target_compile_options(<target> PUBLIC /fsanitize=address)
  else()
    target_compile_options(<target> PUBLIC -fsanitize=address <additional-options>)
    target_link_options(<target> PUBLIC -fsanitize=address)
  endif()
endif()
<additional-options> 部分列出了其他编译标志（如 "-fno-omit-frame-pointer"）。 若要详细了解适用于 Linux 的 AddressSanitizer ，请查看使用 AddressSanitizer。 有关如何将 AddressSanitizer 和 MSVC 结合使用的详细信息，请参阅从开发人员命令提示符使用 AddressSanitizer。
使用  中的 ASAN_OPTIONS 字段将运行时标志传递给 AddressSanitizerlaunch.vs.json。 当未指定其他运行时选项时，ASAN_OPTIONS 默认为 detect_leaks=0，因为 Visual Studio 不支持 LeakSanitizer。
通过命令行或 CI 管道运行 CMake
可以使用相同的  和  文件在 Visual Studio 中以及从命令行调用 CMakeCMakePresets.jsonCMakeUserPresets.json。 CMake 和 CTest 文档是通过 --preset 调用 CMake 和 CTest 的最佳资源。 需要 CMake 版本 3.20 或更高版本。
在 Windows 上使用命令行生成器进行生成时获取环境
在使用命令行生成器进行生成时，由用户先配置环境，再调用 CMake。 若要在 Windows 上使用 Ninja 和 Visual C++ 工具集进行生成，请在调用 CMake 来生成生成系统之前先设置环境。 为此，可使用 architecture 参数调用 vcvarsall.bat。 architecture 参数指定要使用的主机体系结构和目标体系结构。 有关详细信息，请参阅 vcvarsall 语法。 若要在 Linux 或 Windows 上使用 Visual Studio 生成器进行生成，则无需执行此步骤。
这与 Visual Studio 在 IDE 调用 CMake 时所执行的步骤相同。 Visual Studio 为 toolset 和 architecture 指定的主机体系结构和目标体系结构分析当前活动的“配置预设”。 然后，Visual Studio 从  获取指定的环境vcvarsall.bat。 使用 Ninja 从 Windows 命令行进行生成时，需要自行执行此步骤。
 是随 Visual Studio 的生成工具一起安装的vcvarsall.bat。 默认情况下，vcvarsall.bat 安装在 C:\Program Files (x86)\Microsoft Visual Studio\2019\<edition>\VC\Auxiliary\Build 中。 如果你经常使用命令行工作流，则可以将  添加到 PATH 中vcvarsall.bat。
示例命令行工作流
可以使用下面的命令来配置和生成 CMake 项目，此项目使用 Ninja 将 x64 生成工具的目标定为 ARM64。 需要 CMake 版本 3.20 或更高版本。 在  文件所在的目录中运行这些命令CMakePresets.json：
/path/to/vcvarsall.bat x64_arm64 
cmake --list-presets=all .
cmake --preset <configurePreset-name>
cmake --build --preset <buildPreset-name> 
示例  文件CMakePresets.json
box2d-lite 中的  文件包含配置预设、生成预设和测试预设的示例CMakePresets.json。 有关此示例的详细信息，请观看此视频：CMakePresets.json 简介。 可以在 DirectXTK 项目中查看另一个示例，该示例的 configurePresets 部分显示了许多生成目标。
了解有关在 Visual Studio 中配置和调试 CMake 项目的更多信息：
Visual Studio 中的 CMake 项目

自定义 CMake 生成设置

配置 CMake 调试会话

CMake 预定义配置引用