C++ 扩展设置参考

C++ 扩展设置具有高度可配置性。本文介绍了 c_cpp_properties.json 文件的架构。有关 VS Code 中设置的一般信息，请参阅配置设置，以及变量参考和默认 VS Code 设置。

想开始配置您的 C++ 项目吗？请从配置 Intellisense 开始。

变量示例

以下 JSON 代码片段是 c_cpp_properties.json 的配置示例。您只需在 JSON 文件中包含相关的变量，任何缺失的字段将由 C++ 扩展填充为默认值。

{
  "env": {
    "myIncludePath": ["${workspaceFolder}/include", "${workspaceFolder}/src"],
    "myDefines": ["DEBUG", "MY_FEATURE=1"]
  },
  "configurations": [
    {
      "name": "Mac",
      "compilerPath": "/usr/bin/clang++",
      "intelliSenseMode": "macos-clang-x64",
      "includePath": ["${myIncludePath}", "${workspaceFolder}/**"],
      "defines": ["${myDefines}"],
      "cStandard": "c17",
      "cppStandard": "c++20",
      "macFrameworkPath": ["/System/Library/Frameworks", "/Library/Frameworks"],
      "browse": {
        "path": ["${myIncludePath}", "${workspaceFolder}"]
      }
    }
  ],
  "version": 4,
  "enableConfigurationSquiggles": true
}

顶级属性

env：用户定义变量的数组，这些变量可通过标准环境变量语法 ${<var>} 或 ${env:<var>} 在配置中进行替换。接受字符串或字符串数组。
configurations：配置对象数组，为 IntelliSense 引擎提供有关您的项目和首选项的信息。默认情况下，该扩展会根据您的操作系统为您创建一个配置。您也可以添加更多配置。
version：我们建议您不要编辑此字段。它用于跟踪 c_cpp_properties.json 文件的当前版本，以便扩展知道应该存在哪些属性和设置，以及如何将此文件升级到最新版本。
enableConfigurationSquiggles：设置为 true 可将 c_cpp_properties.json 文件中检测到的错误报告给 C++ 扩展。

配置属性

name：标识配置的用户友好名称。Linux、Mac 和 Win32 是在相应平台上自动选择的特殊配置标识符。VS Code 中的状态栏会显示当前活动的配置。您也可以通过选择状态栏中的标签来更改活动的配置。
compilerPath：用于构建项目的编译器的完整路径（例如 /usr/bin/gcc），以启用更准确的 IntelliSense。该扩展会查询编译器以确定用于 IntelliSense 的系统包含路径和默认定义。

设置 "compilerPath": ""（空字符串）将跳过编译器查询。如果您的首选编译器不支持查询所用的参数，此设置非常有用，因为扩展会默认使用它能找到的任何受支持编译器（如 MSVC）。遗漏 compilerPath 属性并不会跳过查询。
compilerArgs：用于修改包含路径或定义的编译器参数，例如 -nostdinc++、-m32 等。带有额外空格分隔参数的参数应作为数组中的单独参数输入，例如，对于 --sysroot <arg>，请使用 \"--sysroot\", \"<arg>\"。
intelliSenseMode：用于映射到特定体系结构的 MSVC、gcc 或 Clang 变体的 IntelliSense 模式。如果未设置或设置为 ${default}，扩展会为该平台选择默认模式。

平台默认值
- Windows: windows-msvc-x64
- Linux: linux-gcc-x64
- macOS: macos-clang-x64
仅指定 <compiler>-<architecture> 变体（例如 gcc-x64）的 IntelliSense 模式属于遗留模式，会根据宿主平台自动转换为 <platform>-<compiler>-<architecture> 变体。
includePath：包含路径是源文件引用的头文件所在的目录。例如，如果源文件包含引用指令 #include "myHeaderFile.h"，则将此头文件的路径添加到 includePath 中。指定一个路径列表，供 IntelliSense 引擎在搜索包含的头文件时使用。在这些路径上的搜索不是递归的。在路径末尾指定 /** 以表示递归搜索。例如，${workspaceFolder}/** 会搜索所有子目录，而 ${workspaceFolder} 则不会。如果您是在安装了 Visual Studio 的 Windows 上，或者已经在 compilerPath 设置中指定了编译器，则此处不应列出系统包含路径。
defines：供 IntelliSense 引擎在解析文件时使用的预处理器定义列表。可以选择使用 = 来设置值，例如 VERSION=1。
cStandard：用于 IntelliSense 的 C 语言标准版本。例如，c17、gnu23 或 ${default}。注意：GNU 标准仅用于查询设置的编译器以获取 GNU 定义，IntelliSense 会模拟相应的 C 标准版本。
cppStandard：用于 IntelliSense 的 C++ 语言标准版本。例如，c++20、gnu++23 或 ${default}。注意：GNU 标准仅用于查询设置的编译器以获取 GNU 定义，IntelliSense 会模拟相应的 C++ 标准版本。
configurationProvider：可以为源文件提供 IntelliSense 配置信息的 VS Code 扩展 ID。例如，使用 VS Code 扩展 ID ms-vscode.cmake-tools 以提供来自 CMake Tools 扩展的配置信息。如果您指定了 configurationProvider，则其提供的配置将优先于您在 c_cpp_properties.json 中的其他设置。

configurationProvider 候选扩展必须实现 vscode-cpptools-api。
mergeConfigurations：设置为 true 可将包含路径、定义和强制包含项与来自配置提供程序的配置合并。
windowsSdkVersion：在 Windows 上使用的 Windows SDK 包含路径版本，例如 10.0.17134.0。
macFrameworkPath：供 IntelliSense 引擎在搜索来自 Mac 框架的包含头文件时使用的路径列表。
forcedInclude：在处理源文件中的任何文本之前应包含的文件列表。文件按列出的顺序包含。
compileCommands：包含工作区 compile_commands.json 文件完整路径的路径数组。如果编辑器中打开的文件在 compile_commands.json 中有匹配条目，则该命令行将用于配置该文件的 IntelliSense，而不是使用 c_cpp_properties.json 的其他字段。有关文件格式的更多信息，请参阅 Clang 文档。某些构建系统（如 CMake）可以简化该文件的生成。
dotConfig：由 Kconfig 系统创建的 .config 文件的路径。Kconfig 系统会生成一个包含构建项目所需所有定义的文件。使用 Kconfig 系统的项目示例包括 Linux 内核和 NuttX RTOS。
customConfigurationVariables：可通过命令 ${cpptools:activeConfigCustomVariable} 查询的自定义变量，用于 launch.json 或 tasks.json 中的输入变量。
browse：与 IntelliSense 结合使用以识别代码库中所有符号的属性集。这些属性由“转到定义/声明”、全局符号搜索等功能使用，或者在“默认”IntelliSense 引擎无法解析源文件中的 #includes 时使用。
recursiveIncludes：一组用于配置扩展如何处理指定了递归搜索的 includePath 条目的属性。

浏览属性

path：其源文件会被解析并用于全局符号搜索的路径列表。如果省略，则 includePath 将被用作 path。默认情况下，这些路径上的搜索是递归的。指定 * 以表示非递归搜索。例如，${workspaceFolder} 会搜索所有子目录，而 ${workspaceFolder}/* 则不会。
limitSymbolsToIncludedHeaders：当设为 true 时，标签解析器仅解析由 ${workspaceFolder} 中的源文件直接或间接包含的头文件。当设为 false 时，标签解析器会解析 browse.path 列表中指定路径下找到的所有代码文件。
databaseFilename：生成的符号数据库路径。此属性指示扩展将工作区符号数据库保存在工作区默认存储位置之外的其他位置。如果指定了相对路径，则它是相对于工作区默认存储位置的，而不是相对于工作区文件夹本身。${workspaceFolder} 变量可用于指定相对于工作区文件夹的路径（例如 ${workspaceFolder}/.vscode/browse.vc.db）。

递归包含属性

reduce：当展开递归 includePath 条目时，可能会产生大量包含路径供 IntelliSense 在解析源文件中的 #include 语句时处理。在某些系统上，将大量的包含路径发送给 IntelliSense 编译器可能会影响 IntelliSense 的性能。默认情况下，扩展会通过首先解析源文件以搜索 #include 语句并确定需要哪些包含路径来标记解析，从而将包含路径集减少为尽可能小的集合。此缩减过程的行为与此设置的 always 选项相同。这种行为权衡了一些初始开销，以便 IntelliSense 在后续运行时可能更快。将此属性设置为 never 将为 IntelliSense 进程提供完整的递归展开路径。通过预先不解析任何文件，这种行为牺牲了潜在的后期性能，以确保在打开源文件时 IntelliSense 能更快启动。通常，减少配置中递归包含路径的数量可能会在涉及大量路径时提高 IntelliSense 的性能。
priority：解析 #include 语句时递归包含路径搜索的优先级。如果设置为 beforeSystemIncludes，则会在系统包含路径之前搜索递归包含路径。如果设置为 afterSystemIncludes，则会在系统包含路径之后搜索递归包含路径。beforeSystemIncludes 更能反映编译器的搜索顺序，从而带来更好的可预测性，而 afterSystemIncludes 可能会提高性能。
order：递归包含的子目录是按 breadthFirst（广度优先）还是 depthFirst（深度优先）搜索。

支持的变量

您可以允许 tasks.json 或 launch.json 查询 c_cpp_properties.json 中当前的活动配置。为此，请在 tasks.json 或 launch.json 脚本中将 ${command:cpptools.activeConfigName} 变量作为参数使用。

默认 VS Code 设置

所有默认的 VS Code 设置（例如 C_Cpp.default.includePath）均在 c_cpp_properties.json 中受支持。唯一的例外是：

C_Cpp.default.systemIncludePath : string[]

此设置允许您将系统包含路径与包含路径分开指定。然而，C++ 扩展从编译器接收到的所选系统包含路径并不会传递给 IntelliSense 进程。这仅在极少数情况下使用，因为它会覆盖标准的编译器行为（例如，如果您的编译器不受支持）。相反，请使用 compilerArgs 设置并使用 -isystem 标志来指定系统头文件，这在大多数情况下是更好的解决方案。

4/25/2025