尝试以扩展 VS Code 中的代理模式！

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)。扩展会查询编译器以确定用于智能感知的系统包含路径和默认定义。

    将 "compilerPath": ""（空字符串）设置为跳过查询编译器。如果您的首选编译器不支持用于查询的参数，这会很有用，因为扩展会默认使用它能找到的任何受支持的编译器（如 MSVC）。省略 compilerPath 属性不会跳过查询。

  • compilerArgs: 用于修改包含路径或定义的编译器参数，例如 -nostdinc++、-m32 等。需要额外以空格分隔参数的参数应在数组中作为单独的参数输入，例如，对于 --sysroot <arg>，请使用 \"--sysroot\", \"<arg>\"。

  • intelliSenseMode: 要使用的智能感知 (IntelliSense) 模式，它映射到特定于体系结构的 MSVC、gcc 或 Clang 变体。如果未设置或设置为 ${default}，扩展会为该平台选择默认值。

    平台默认值

    • Windows: windows-msvc-x64
    • Linux: linux-gcc-x64
    • macOS: macos-clang-x64

    仅指定 <compiler>-<architecture> 变体（例如 gcc-x64）的智能感知模式是旧模式，会根据主机平台自动转换为 <platform>-<compiler>-<architecture> 变体。

  • includePath: 一个包含路径，是源文件所包含的头文件目录。例如，一个源文件包含 #include "myHeaderFile.h" 指令，将此头文件的路径添加到 includePath。为智能感知 (IntelliSense) 引擎在搜索包含的头文件时指定一个路径列表。在这些路径上的搜索不是递归的。在路径末尾指定 /** 表示递归搜索。例如，${workspaceFolder}/** 将搜索所有子目录，而 ${workspaceFolder} 不会。如果您在 Windows 上安装了 Visual Studio，或者在 compilerPath 设置中指定了编译器，系统包含路径不应在此处列出。

  • defines: 供智能感知 (IntelliSense) 引擎在解析文件时使用的预处理器定义列表。可选地，使用 = 来设置一个值，例如 VERSION=1。

  • cStandard: 用于智能感知 (IntelliSense) 的 C 语言标准版本。例如，c17、gnu23 或 ${default}。注意：GNU 标准仅用于查询设置的编译器以获取 GNU 定义，智能感知会模拟等效的 C 标准版本。

  • cppStandard: 用于智能感知 (IntelliSense) 的 C++ 语言标准版本。例如，c++20、gnu++23 或 ${default}。注意：GNU 标准仅用于查询设置的编译器以获取 GNU 定义，智能感知会模拟等效的 C++ 标准版本。

  • configurationProvider: 一个 VS Code 扩展的 ID，该扩展可以为源文件提供智能感知 (IntelliSense) 配置信息。例如，使用 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) 结合使用的一组属性，用于识别您代码库中的所有符号。这些属性被“转到定义/声明”、全局符号搜索等功能使用，或者当“默认”智能感知引擎无法解析源文件中的 #includes 时使用。

  • recursiveIncludes: 用于配置扩展如何处理指定递归搜索的 includePath 条目的一组属性。

浏览属性

  • path: 一个路径列表，其源文件被解析后用于全局符号搜索。如果省略，includePath 将被用作 path。在这些路径上的搜索默认是递归的。指定 * 表示非递归搜索。例如，${workspaceFolder} 搜索所有子目录，而 ${workspaceFolder}/* 不会。

  • limitSymbolsToIncludedHeaders: 当为 true 时，Tag Parser 仅解析由 ${workspaceFolder} 中的源文件直接或间接包含的头文件。当为 false 时，Tag Parser 解析在 browse.path 列表中指定路径中找到的所有代码文件。

  • databaseFilename: 生成的符号数据库的路径。此属性指示扩展将工作区符号数据库保存在工作区默认存储位置之外的某个地方。如果指定了相对路径，它将相对于工作区的默认存储位置，而不是工作区文件夹本身。可以使用 ${workspaceFolder} 变量来指定相对于工作区文件夹的路径（例如 ${workspaceFolder}/.vscode/browse.vc.db）。

递归包含属性

  • reduce: 当一个递归的 includePath 条目被展开时，可能会产生一个非常大的包含路径集合供智能感知 (IntelliSense) 在解析源文件中的 #include 语句时处理。向智能感知编译器发送大量的包含路径可能会影响某些系统上智能感知的性能。默认情况下，扩展将通过首先标记解析源文件以搜索 #include 语句并确定需要哪些包含路径，来将包含路径集合缩减到最小可能集合。此缩减过程与此设置的 always 选项的行为相同。这种行为以一些初始开销为代价，以便智能感知稍后可能更快。将此属性设置为 never 将向智能感知进程提供完整的递归展开的包含路径。通过不预先解析任何文件，这种行为以潜在的后续性能为代价，以确保在打开源文件时智能感知可以更快地启动。通常，在涉及大量路径时，减少配置中的递归包含路径数量可能会提高智能感知的性能。

  • 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 设置

c_cpp_properties.json 支持所有默认的 VS Code 设置，例如 C_Cpp.default.includePath。唯一的例外是

C_Cpp.default.systemIncludePath : string[]

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

4/25/2025