參加你附近的 ，瞭解 VS Code 中的 AI 輔助開發。

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：要使用的智慧感知模式，它對映到特定於體系結構的 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 中。指定一個路徑列表，供智慧感知引擎在搜尋包含的標頭檔案時使用。在這些路徑上的搜尋不是遞迴的。在路徑末尾指定 /** 以表示遞迴搜尋。例如，${workspaceFolder}/** 會搜尋所有子目錄，而 ${workspaceFolder} 則不會。如果您在 Windows 上安裝了 Visual Studio，或者在 compilerPath 設定中指定了編譯器，則不應在此處列出系統包含路徑。

  • defines：供智慧感知引擎在解析檔案時使用的預處理器定義列表。可以選擇使用 = 來設定值，例如 VERSION=1。

  • cStandard：用於智慧感知的 C 語言標準版本。例如，c17、gnu23 或 ${default}。注意：GNU 標準僅用於查詢已設定的編譯器以獲取 GNU 定義，而智慧感知會模擬等效的 C 標準版本。

  • cppStandard：用於智慧感知的 C++ 語言標準版本。例如，c++20、gnu++23 或 ${default}。注意：GNU 標準僅用於查詢已設定的編譯器以獲取 GNU 定義，而智慧感知會模擬等效的 C++ 標準版本。

  • configurationProvider：一個 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：一個路徑列表，供智慧感知引擎在搜尋 Mac 框架中的包含標頭檔案時使用。

  • forcedInclude：一個檔案列表，這些檔案應在處理原始檔中的任何文字之前被包含。檔案按列出的順序包含。

  • compileCommands：一個包含工作區 compile_commands.json 檔案完整路徑的路徑陣列。如果在 compile_commands.json 中有與編輯器中開啟的檔案匹配的條目，則該命令列將用於為該檔案配置智慧感知，而不是使用 c_cpp_properties.json 的其他欄位。有關檔案格式的更多資訊，請參閱 Clang 文件。一些構建系統，如 CMake，可以簡化此檔案的生成。

  • dotConfig：一個指向 .config 檔案的路徑，該檔案由 Kconfig 系統建立。Kconfig 系統會生成一個包含構建專案所需的所有宏定義的檔案。使用 Kconfig 系統的專案示例包括 Linux 核心和 NuttX RTOS。

  • customConfigurationVariables：可透過命令 ${cpptools:activeConfigCustomVariable} 查詢的自定義變數，用於 launch.json 或 tasks.json 中的輸入變數。

  • browse：與智慧感知結合使用的一組屬性，用於識別程式碼庫中的所有符號。這些屬性被諸如**轉到定義/宣告**、全域性符號搜尋等功能使用，或者在“預設”智慧感知引擎無法解析原始檔中的 #includes 時使用。

  • recursiveIncludes：一組用於配置擴充套件如何處理指定遞迴搜尋的 includePath 條目的屬性。

瀏覽屬性

  • path：一個路徑列表，其原始檔將被解析以用於全域性符號搜尋。如果省略，includePath 將被用作 path。在這些路徑上的搜尋預設是遞迴的。指定 * 表示非遞迴搜尋。例如，${workspaceFolder} 會搜尋所有子目錄，而 ${workspaceFolder}/* 則不會。

  • limitSymbolsToIncludedHeaders：當為 true 時，Tag 解析器僅解析由 ${workspaceFolder} 中的原始檔直接或間接包含的標頭檔案。當為 false 時，Tag 解析器會解析在 browse.path 列表中指定路徑中找到的所有程式碼檔案。

  • databaseFilename：生成的符號資料庫的路徑。此屬性指示擴充套件將工作區符號資料庫儲存在工作區的預設儲存位置之外的其他地方。如果指定了相對路徑，它將相對於工作區的預設儲存位置，而不是工作區資料夾本身。${workspaceFolder} 變數可用於指定相對於工作區資料夾的路徑（例如 ${workspaceFolder}/.vscode/browse.vc.db）。

遞迴包含屬性

  • reduce：當一個遞迴的 includePath 條目被展開時，可能會為智慧感知在解析原始檔中的 #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++ 擴充套件從編譯器接收到的所選系統包含路徑不會傳遞給智慧感知過程。這僅在極少數情況下使用，因為它會覆蓋標準的編譯器行為，例如，如果您的編譯器不受支援。相反，應使用 compilerArgs 設定和 -isystem 標誌來指定系統標頭檔案，這在大多數情況下是更好的解決方案。

4/25/2025