🚀 在 VS Code 中！

變數參考

Visual Studio Code 支援在偵錯和工作組態檔以及一些選取的設定中使用變數替換。在使用 ${variableName} 語法時，launch.json 和 tasks.json 檔案中的某些索引鍵和值字串內支援變數替換。

預先定義的變數

支援下列預先定義的變數

  • ${userHome} - 使用者首頁資料夾的路徑
  • ${workspaceFolder} - 在 VS Code 中開啟的資料夾路徑
  • ${workspaceFolderBasename} - 在 VS Code 中開啟的資料夾名稱，不含任何斜線 (/)
  • ${file} - 目前開啟的檔案
  • ${fileWorkspaceFolder} - 目前開啟檔案的工作區資料夾
  • ${relativeFile} - 相對於 workspaceFolder 的目前開啟檔案
  • ${relativeFileDirname} - 相對於 workspaceFolder 的目前開啟檔案目錄名稱
  • ${fileBasename} - 目前開啟檔案的檔案名稱
  • ${fileBasenameNoExtension} - 目前開啟檔案的檔案名稱，不含副檔名
  • ${fileExtname} - 目前開啟檔案的副檔名
  • ${fileDirname} - 目前開啟檔案的資料夾路徑
  • ${fileDirnameBasename} - 目前開啟檔案的資料夾名稱
  • ${cwd} - 在 VS Code 啟動時，工作執行器的目前工作目錄
  • ${lineNumber} - 活動檔案中目前選取的行號
  • ${columnNumber} - 活動檔案中目前選取的欄號
  • ${selectedText} - 活動檔案中目前選取的文字
  • ${execPath} - 正在執行的 VS Code 可執行檔路徑
  • ${defaultBuildTask} - 預設建置工作的名稱
  • ${pathSeparator} - 作業系統用於分隔檔案路徑中元件的字元
  • ${/} - ${pathSeparator} 的簡寫

預先定義的變數範例

假設您有下列需求

  1. 檔案位於 /home/your-username/your-project/folder/file.ext，在您的編輯器中開啟；
  2. 目錄 /home/your-username/your-project 以根工作區開啟。

因此，每個變數都會有下列值

  • ${userHome} - /home/your-username
  • ${workspaceFolder} - /home/your-username/your-project
  • ${workspaceFolderBasename} - your-project
  • ${file} - /home/your-username/your-project/folder/file.ext
  • ${fileWorkspaceFolder} - /home/your-username/your-project
  • ${relativeFile} - folder/file.ext
  • ${relativeFileDirname} - folder
  • ${fileBasename} - file.ext
  • ${fileBasenameNoExtension} - file
  • ${fileExtname} - .ext
  • ${fileDirname} - /home/your-username/your-project/folder
  • ${fileDirnameBasename} - folder
  • ${lineNumber} - 游標的行號
  • ${columnNumber} - 游標的欄號
  • ${selectedText} - 在程式碼編輯器中選取的文字
  • ${execPath} - Code.exe 的位置
  • ${pathSeparator} - macOS 或 Linux 上為 /，Windows 上為 \

提示：在 tasks.json 和 launch.json 的字串值內使用 IntelliSense，以取得預先定義變數的完整清單。

工作區資料夾範圍的變數

透過將根資料夾的名稱附加到變數 (以冒號分隔)，可以存取工作區的同層級根資料夾。若沒有根資料夾名稱，變數的範圍會限定為使用它的相同資料夾。

例如，在具有 Server 和 Client 資料夾的多根工作區中，${workspaceFolder:Client} 是指 Client 根的路徑。

環境變數

您也可以透過 ${env:Name} 語法 (例如，${env:USERNAME}) 參考環境變數。

{
  "type": "node",
  "request": "launch",
  "name": "Launch Program",
  "program": "${workspaceFolder}/app.js",
  "cwd": "${workspaceFolder}",
  "args": ["${env:USERNAME}"]
}

組態變數

您可以透過 ${config:Name} 語法 (例如，${config:editor.fontSize}) 參考 VS Code 設定 ("組態")。

命令變數

如果上述預先定義的變數不足，您可以透過 ${command:commandID} 語法將任何 VS Code 命令當作變數使用。

命令變數會被命令評估的 (字串) 結果取代。命令的實作範圍可以從簡單的計算 (不含 UI) 到以透過 VS Code 擴充功能 API 提供的 UI 功能為基礎的某些複雜功能。如果命令傳回字串以外的任何內容，則變數替換將不會完成。命令變數必須傳回字串。

此功能的一個範例在 VS Code 的 Node.js 偵錯工具擴充功能中，其提供互動式命令 extension.pickNodeProcess，可從所有正在執行的 Node.js 處理序清單中選取單一處理序。命令會傳回選取處理序的處理序 ID。這使得可以在依處理序 ID 附加啟動組態中使用 extension.pickNodeProcess 命令，方法如下

{
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach by Process ID",
      "processId": "${command:extension.pickNodeProcess}"
    }
  ]
}

在 launch.json 組態中使用命令變數時，封閉的 launch.json 組態會當作物件透過引數傳遞至命令。這允許命令在呼叫時知道特定 launch.json 組態的內容和參數。

輸入變數

命令變數已經很強大，但它們缺少為特定使用案例設定執行中命令的機制。例如，無法將提示訊息或預設值傳遞至一般 "使用者輸入提示"。

此限制透過輸入變數解決，其語法為：${input:variableID}。variableID 是指 launch.json 和 tasks.json 的 inputs 區段中的項目，其中指定了其他組態屬性。不支援輸入變數的巢狀結構。

下列範例顯示使用輸入變數的 tasks.json 的整體結構

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "task name",
      "command": "${input:variableID}"
      // ...
    }
  ],
  "inputs": [
    {
      "id": "variableID",
      "type": "type of input variable"
      // type specific configuration attributes
    }
  ]
}

目前 VS Code 支援三種輸入變數類型

  • promptString：顯示輸入方塊以從使用者取得字串。
  • pickString：顯示快速選取下拉式清單，讓使用者從多個選項中選取。
  • command：執行任意命令。

每種類型都需要其他組態屬性

promptString:

  • description：顯示在快速輸入中，提供輸入的內容。
  • default：如果使用者未輸入其他內容，將使用的預設值。
  • password：設定為 true 以使用密碼提示輸入，不會顯示輸入的值。

pickString:

  • description：顯示在快速選取中，提供輸入的內容。
  • options：使用者可從中選取的選項陣列。
  • default：如果使用者未輸入其他內容，將使用的預設值。它必須是選項值之一。

選項可以是字串值或同時具有標籤和值的物件。下拉式清單將顯示 label: value。

command:

  • command：在變數內插補點時執行的命令。
  • args：傳遞至命令實作的選用選項包。

以下是 tasks.json 的範例，說明如何使用 Angular CLI 的 inputs

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "ng g",
      "type": "shell",
      "command": "ng",
      "args": ["g", "${input:componentType}", "${input:componentName}"]
    }
  ],
  "inputs": [
    {
      "type": "pickString",
      "id": "componentType",
      "description": "What type of component do you want to create?",
      "options": [
        "component",
        "directive",
        "pipe",
        "service",
        "class",
        "guard",
        "interface",
        "enum"
      ],
      "default": "component"
    },
    {
      "type": "promptString",
      "id": "componentName",
      "description": "Name your component.",
      "default": "my-new-component"
    }
  ]
}

執行範例

Inputs Example

下列範例示範如何在偵錯組態中使用 command 類型的使用者輸入變數，讓使用者從特定資料夾中找到的所有測試案例清單中挑選測試案例。假設某些擴充功能提供 extension.mochaSupport.testPicker 命令，該命令會找出可組態位置中的所有測試案例，並顯示選取器 UI 以挑選其中一個案例。命令輸入的引數由命令本身定義。

{
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Run specific test",
      "program": "${workspaceFolder}/${input:pickTest}"
    }
  ],
  "inputs": [
    {
      "id": "pickTest",
      "type": "command",
      "command": "extension.mochaSupport.testPicker",
      "args": {
        "testFolder": "/out/tests"
      }
    }
  ]
}

命令輸入也可以與工作搭配使用。在此範例中，使用內建的終止工作命令。它可以接受引數以終止所有工作。

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Terminate All Tasks",
      "command": "echo ${input:terminate}",
      "type": "shell",
      "problemMatcher": []
    }
  ],
  "inputs": [
    {
      "id": "terminate",
      "type": "command",
      "command": "workbench.action.tasks.terminate",
      "args": "terminateAll"
    }
  ]
}

常見問題

偵錯組態或工作中變數替換的詳細資訊

偵錯組態或工作中的變數替換是兩個階段的處理程序

  • 在第一階段中，所有變數都會評估為字串結果。如果變數出現多次，則只會評估一次。
  • 在第二階段中，所有變數都會替換為第一階段的結果。

這樣做的結果是，變數的評估 (例如，在擴充功能中實作的命令型變數) 無法存取偵錯組態或工作中的其他已替換變數。它只會看到原始變數。這表示變數不能相互依賴 (這可確保隔離，並使替換在評估順序方面更穩固)。

使用者和工作區設定中是否支援變數替換？

在 settings.json 檔案中的選取設定索引鍵中支援預先定義的變數，例如終端機 cwd、env、shell 和 shellArgs 值。某些設定 (例如 window.title) 有自己的變數

  "window.title": "${dirty}${activeEditorShort}${separator}${rootName}${separator}${appName}"

請參閱設定編輯器 (⌘, (Windows、Linux Ctrl+,)) 中的註解，以瞭解設定特定變數的相關資訊。

為什麼沒有記錄 ${workspaceRoot}？

變數 ${workspaceRoot} 已淘汰，改用 ${workspaceFolder}，以更好地與多根工作區支援對齊。

為什麼 tasks.json 中的變數未解析？

並非 tasks.json 中的所有值都支援變數替換。具體而言，只有 command、args 和 options 支援變數替換。inputs 區段中的輸入變數將不會解析，因為不支援輸入變數的巢狀結構。

我如何知道變數的實際值？

檢查變數執行階段值的一種簡單方法是建立 VS Code 工作，以將變數值輸出到主控台。例如，若要查看 ${workspaceFolder} 的已解析值，您可以在 tasks.json 中建立並執行 (終端機 > 執行工作) 下列簡單的 'echo' 工作

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "echo",
      "type": "shell",
      "command": "echo ${workspaceFolder}"
    }
  ]
}
02/06/2025