變數參考

Visual Studio Code 支援在偵錯 (Debugging) 與工作 (Task) 設定檔中進行變數替換，部分特定設定亦支援。透過使用 ${variableName} 語法，可以在 launch.json 與 tasks.json 檔案的某些索引鍵與字串值中使用變數替換。

預先定義的變數

支援下列預先定義的變數

預先定義變數範例

假設您有下列情況

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 為 \

平台與工作區注意事項

平台專屬行為

某些預先定義變數的解析方式可能會依作業系統而異

• 在 Windows 上，檔案路徑使用反斜線 (\)。當在 tasks.json 或 launch.json 等 JSON 檔案中撰寫路徑時，請確保正確跳脫反斜線（例如："${workspaceFolder}\\subdir"）。
• 在 macOS 與 Linux 上，檔案路徑使用正斜線 (/)。

建議使用 ${pathSeparator} 或 ${/}，以確保設定能在不同平台間移植。

各工作區資料夾的變數範圍

透過在變數後附加根資料夾名稱（以冒號分隔），可以存取工作區的同級根資料夾。若未指定根資料夾名稱，該變數的範圍將僅限於使用它的資料夾。

例如，在包含 Server 與 Client 資料夾的多根工作區中，${workspaceFolder:Client} 指的是 Client 根目錄的路徑。

環境變數

您可以使用 ${env:Name} 語法來參考環境變數。例如，${env:USERNAME} 會參考 USERNAME 環境變數。

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

設定變數

若要參考 VS Code 設定 (configurations)，請使用 ${config:Name} 語法。例如，${config:editor.fontSize} 會參考 editor.fontSize 設定。

命令變數

您可以使用 ${command:commandID} 語法，將任何 VS Code 命令當作變數使用。

命令變數會被替換為命令執行後的（字串）結果。命令的實作方式可以從沒有 UI 的簡單計算，到基於 VS Code 擴充功能 API 所提供之 UI 功能的複雜功能。如果命令回傳的不是字串，變數替換將無法完成。命令變數必須回傳字串。

此功能的一個範例是 VS Code 的 Node.js 偵錯器擴充功能，它提供了一個互動式命令 extension.pickNodeProcess，用於從所有正在執行的 Node.js 處理序清單中選取一個處理序。該命令會回傳所選處理序的處理序 ID。這使得在依處理序 ID 附加 (Attach by Process 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：顯示 Quick Pick 下拉式選單，讓使用者從多個選項中選取。
• command：執行任意命令。

每種類型都需要額外的設定屬性

promptString:

• description：顯示在快速輸入中，提供輸入的內容說明。
• default：若使用者未輸入其他內容時所使用的預設值。
• password：設為 true 可使用密碼輸入提示，且不會顯示輸入的內容。

pickString:

• description：顯示在快速選取中，提供輸入的內容說明。
• options：供使用者選擇的選項陣列。
• default：若使用者未輸入其他內容時所使用的預設值。必須為選項值之一。

選項可以是字串值，或是同時包含標籤 (label) 與值 (value) 的物件。下拉式選單將顯示為 label: value。

命令:

• command：在變數插補 (interpolation) 時執行命令。
• args：傳遞給命令實作的可選參數包。

以下是一個使用 Angular CLI 的 tasks.json 範例，示範了 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"
    }
  ]
}

執行範例

下列範例顯示如何在偵錯設定中使用 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"
      }
    }
  ]
}

命令輸入也可以用於工作。在此範例中，使用了內建的終止工作 (Terminate Task) 命令。它可以接受引數來終止所有工作。

{
  "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 在 VS Code 中開啟 在 VS Code Insiders 中開啟 ）擁有它們專屬的變數。

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

請參閱設定編輯器中的註解（⌘, (Windows, Linux Ctrl+,)），以瞭解設定專屬變數。

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

為了更好地配合多根工作區 (Multi-root Workspace) 的支援，${workspaceRoot} 變數已被棄用，建議改用 ${workspaceFolder}。

為什麼 tasks.json 中的變數沒有被解析？

並非 tasks.json 中的所有值都支援變數替換。具體來說，僅 command、args 與 options 支援變數替換。由於不支援巢狀輸入變數，inputs 區段中的輸入變數將不會被解析。

如何得知變數的實際值？

檢查變數執行時期值的一個簡單方法是建立一個 VS Code 工作，將變數值輸出到主控台。例如，若要查看 ${workspaceFolder} 的解析值，您可以建立並執行（終端機 (Terminal) > 執行工作 (Run Task)）tasks.json 中的這個簡單 'echo' 工作：

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

相關資源

• 偵錯
• 工作 (Tasks)