C++ 擴充功能設定參考

C++ 擴充功能的設定具有高度可配置性。本文說明 c_cpp_properties.json 檔案的結構描述。關於 VS Code 設定的一般資訊，請參考設定設定 (Configure settings)，以及變數參考和預設 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 的系統包含路徑 (include paths) 和預設定義。

設定 "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> 變體的 IntelliSense 模式（例如 gcc-x64）為舊版模式，系統會根據主機平台自動轉換為 <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 可將包含路徑、定義與強制包含項目與設定提供者 (configuration provider) 的項目進行合併。
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 Kernel 與 NuttX RTOS。
customConfigurationVariables：可透過指令 ${cpptools:activeConfigCustomVariable} 查詢的自訂變數，用於 launch.json 或 tasks.json 中的輸入變數。
browse：與 IntelliSense 結合使用以識別程式碼庫中所有符號的屬性集。這些屬性供「移至定義/宣告」、全域符號搜尋等功能使用，或在「預設」IntelliSense 引擎無法解析原始程式碼檔案中的 #includes 時使用。
recursiveIncludes：用於設定擴充功能如何處理指定遞迴搜尋之 includePath 項目的一組屬性。

瀏覽 (Browse) 屬性

path：其原始程式碼檔案將被剖析並用於全域符號搜尋的路徑清單。若省略，則使用 includePath 作為 path。預設情況下，這些路徑的搜尋為遞迴搜尋。指定 * 表示非遞迴搜尋。例如，${workspaceFolder} 會搜尋所有子目錄，而 ${workspaceFolder}/* 則不會。
limitSymbolsToIncludedHeaders：若設為 true，標籤剖析器 (Tag Parser) 僅會剖析 ${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