Visual Studio Code 偵錯設定

Name: Visual Studio Code
Author: Microsoft

對於複雜的偵錯情境或應用程式，您需要建立 launch.json 檔案來指定偵錯工具設定。例如：指定應用程式進入點、附加至執行中的應用程式，或是設定環境變數。

若要深入了解 VS Code 中的偵錯，請參閱 Visual Studio Code 中的偵錯。

提示

VS Code 中的 Copilot 可以協助您為專案建立啟動設定。取得更多關於使用 Copilot 產生啟動設定的資訊。

啟動設定

對於簡單的應用程式或偵錯情境，您不需要特定的偵錯設定即可執行和偵錯程式。使用 F5 鍵，VS Code 就會嘗試執行您目前作用中的檔案。

然而，對於大多數的偵錯情境，您需要建立偵錯設定 (啟動設定)。例如，指定應用程式進入點、附加至執行中的應用程式，或設定環境變數。建立啟動設定檔案也很有好處，因為它允許您將偵錯設定詳細資料與專案一起設定並儲存。

VS Code 會將偵錯設定資訊儲存在位於工作區 (專案根資料夾) 中 .vscode 資料夾內的 launch.json 檔案中，或是儲存在您的使用者設定或工作區設定中。

下列程式碼片段描述了用於偵錯 Node.js 應用程式的範例設定

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "skipFiles": ["<node_internals>/**"],
      "program": "${workspaceFolder}\\app.js"
    }
  ]
}

VS Code 也支援複合啟動設定，以便同時啟動多個設定。

注意

即使您未在 VS Code 中開啟資料夾，也可以偵錯簡單的應用程式，但無法管理啟動設定和設定進階偵錯。

建立偵錯設定檔案

若要建立初始的 launch.json 檔案

在「執行與偵錯」檢視中選取建立 launch.json 檔案。
VS Code 會嘗試偵測您的偵錯環境。如果無法偵測，您可以手動選擇它

根據所選的偵錯環境，VS Code 會在 launch.json 檔案中建立入門設定。
在「總管」檢視 (⇧⌘E (Windows, Linux Ctrl+Shift+E)) 中，請注意 VS Code 已建立 .vscode 資料夾，並將 launch.json 檔案新增至您的工作區。

您現在可以編輯 launch.json 檔案以新增更多設定或修改現有設定。

將設定新增至 launch.json

若要將新設定新增至現有的 launch.json，請使用下列其中一種技巧

按下新增設定按鈕，然後選取程式碼片段以新增預先定義的設定。
如果您的游標位於 configurations 陣列內，請使用 IntelliSense。
選擇執行 > 新增設定功能表選項。

launch json suggestions

使用 AI 產生啟動設定

透過 VS Code 中的 Copilot，您可以加速為專案建立啟動設定的過程。若要使用 Copilot 產生啟動設定

使用 ⌃⌘I (Windows, Linux Ctrl+Alt+I) 開啟「聊天」檢視，或從標題列的 Copilot 功能表中選取開啟聊天。
輸入 /startDebugging 聊天提示來產生偵錯設定。

或者，您也可以輸入自訂提示，例如 generate a debug config for an express app #codebase。

如果您的工作區包含使用不同語言的檔案，這會很有用。

注意
#codebase 聊天變數為 Copilot 提供了您的專案內容，有助於它產生更準確的回應。
套用建議的設定，然後開始偵錯。

使用啟動設定啟動偵錯工作階段

若要使用啟動設定啟動偵錯工作階段

在「執行與偵錯」檢視中使用設定下拉式方塊選取名為啟動程式的設定。

可用設定的清單與 launch.json 檔案中的設定相符。
使用 F5 啟動您的偵錯工作階段，或在「執行與偵錯」檢視中選取開始偵錯 (播放圖示)。

或者，您可以透過命令選擇區 (⇧⌘P (Windows, Linux Ctrl+Shift+P))，依偵錯: 選取並開始偵錯進行篩選，或輸入 'debug ' 並選取您想要偵錯的設定來執行您的設定。

啟動與附加設定的比較

在 VS Code 中，有兩個核心偵錯模式：啟動 (Launch) 與附加 (Attach)，它們分別處理兩種不同的工作流程和開發人員群組。根據您的工作流程，可能會很難分清楚哪種設定類型才適合您的專案。

如果您具備瀏覽器開發人員工具背景，您可能不習慣「從您的工具啟動」，因為您的瀏覽器執行個體已經開啟了。當您開啟開發人員工具時，您只是將開發人員工具附加到您已開啟的瀏覽器分頁。另一方面，如果您具備伺服器或桌面背景，讓您的編輯器幫您啟動處理程序，且編輯器會自動將其偵錯工具附加至新啟動的處理程序，這是相當正常的。

解釋啟動與附加之間差異的最佳方式，是將啟動設定視為在 VS Code 附加至應用程式之前，如何在偵錯模式下啟動應用程式的操作說明；而附加設定則是關於如何將 VS Code 的偵錯工具連接到已經在執行中的應用程式或處理程序的說明。

VS Code 偵錯工具通常支援在偵錯模式下啟動程式，或是附加至已經在偵錯模式下執行的程式。根據要求類型 (attach 或 launch)，所需的屬性會有所不同，而 VS Code 的 launch.json 驗證和建議功能應該能提供協助。

Launch.json 屬性

有許多 launch.json 屬性可用來支援不同的偵錯工具和偵錯情境。一旦您為 type 屬性指定了值，就可以使用 IntelliSense (⌃Space (Windows, Linux Ctrl+Space)) 來查看可用屬性的清單。不同偵錯工具可用的啟動設定屬性會有所不同。

launch json suggestions

適用於某個偵錯工具的屬性，不一定會自動適用於其他偵錯工具。如果您在啟動設定中看到紅色波浪線，請將滑鼠游標停留在上方以了解問題所在，並在啟動偵錯工作階段之前嘗試修正它們。

下列屬性是每個啟動設定所必須的

type - 用於此啟動設定的偵錯工具類型。每個已安裝的偵錯擴充功能都會引入一個類型：例如，內建 Node 偵錯工具為 node，PHP 和 Go 擴充功能則分別為 php 和 go。
request - 此啟動設定的要求類型。目前支援 launch 在 VS Code 中開啟在 VS Code Insiders 中開啟與 attach。
name - 顯示在偵錯啟動設定下拉式方塊中、對讀者友善的名稱。

以下是適用於所有啟動設定的一些選擇性屬性

presentation - 透過使用 presentation 物件中的 order、group 和 hidden 屬性，您可以在偵錯設定下拉式方塊與偵錯快速挑選中排序、分組和隱藏設定與複合設定。您也可以在平台特有區段 (windows、linux、osx) 內設定 presentation，以控制每個作業系統的能見度。
preLaunchTask - 若要在偵錯工作階段開始之前啟動工作，請將此屬性設定為指定於 tasks.json (位於工作區的 .vscode 資料夾中) 內的工作標籤。或者，可以將其設定為 ${defaultBuildTask} 以使用您的預設建置工作。
postDebugTask - 若要在偵錯工作階段結束時啟動工作，請將此屬性設定為指定於 tasks.json (位於工作區的 .vscode 資料夾中) 內的工作名稱。
internalConsoleOptions - 此屬性可控制偵錯工作階段期間偵錯主控台面板的能見度。
debugServer - 僅適用於偵錯擴充功能作者：此屬性允許您連線至指定的連接埠，而不是啟動偵錯介面卡。
serverReadyAction - 如果您希望每當正在偵錯的程式向偵錯主控台或整合式終端機輸出特定訊息時，就在網頁瀏覽器中開啟 URL。如需詳細資料，請參閱下方偵錯伺服器程式時自動開啟 URI 一節。

許多偵錯工具支援下列部分屬性

program - 啟動偵錯工具時要執行的可執行檔或檔案
args - 傳遞給要偵錯之程式的引數
env - 環境變數 (可以使用 null 值來「取消定義」變數)
envFile - 包含環境變數之 dotenv 檔案的路徑
cwd - 用於尋找相依性與其他檔案目前的工作目錄
port - 附加至執行中處理程序時的連接埠
stopOnEntry - 當程式啟動時立即中斷
console - 要使用哪種主控台，例如 internalConsole、integratedTerminal 或 externalTerminal

變數替換

VS Code 將常用路徑和其他值提供作為變數，並支援在 launch.json 的字串內進行變數替換。這表示您不需要在偵錯設定中使用絕對路徑。例如，${workspaceFolder} 提供工作區資料夾的根路徑，${file} 提供在作用中編輯器中開啟的檔案，而 ${env:Name} 提供環境變數 'Name'。

您可以在變數參考中查看預先定義變數的完整清單，或透過在 launch.json 字串屬性內叫用 IntelliSense 來查看。

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

平台特有的屬性

VS Code 支援定義取決於執行偵錯工具之作業系統的偵錯設定 (例如，要傳遞給程式的引數)。若要這樣做，請在 launch.json 檔案中放入平台特有的常值，並在該常值內指定對應的屬性。

下列範例顯示如何在 Windows 上以不同方式將 "args" 傳遞給程式

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js",
      "args": ["myFolder/path/app.js"],
      "windows": {
        "args": ["myFolder\\path\\app.js"]
      }
    }
  ]
}

有效的作業系統屬性為：Windows 的 "windows"、Linux 的 "linux"，以及 macOS 的 "osx"。在作業系統特定範圍中定義的屬性會覆寫在全域範圍中定義的屬性。

type 屬性不能放在平台特有區段內，因為在遠端偵錯情境中，type 會間接決定平台，這會導致循環相依性。

在下列範例中，偵錯程式時總是會在進入點停止，但 macOS 除外

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js",
      "stopOnEntry": true,
      "osx": {
        "stopOnEntry": false
      }
    }
  ]
}

您也可以使用平台特有區段來控制 presentation 屬性。在下列範例中，該設定在 macOS 上會從偵錯下拉式方塊中隱藏

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "program": "${workspaceFolder}/app.js",
      "osx": {
        "presentation": {
          "hidden": true
        }
      }
    }
  ]
}

全域啟動設定

您可以定義適用於所有工作區的啟動設定。若要指定全域啟動設定，請在您的 launch 在 VS Code 中開啟在 VS Code Insiders 中開啟使用者設定中新增啟動設定物件。然後，此 launch 設定就會在您的工作區之間共用。例如：

"launch": {
    "version": "0.2.0",
    "configurations": [{
        "type": "node",
        "request": "launch",
        "name": "Launch Program",
        "program": "${file}"
    }]
}

重新導向偵錯目標的輸入/輸出

重新導向輸入/輸出是與偵錯工具或執行階段相關的，因此 VS Code 沒有適用於所有偵錯工具的內建解決方案。

以下是您可能會想要考慮的兩種方法

在終端機或命令提示字元中手動啟動要偵錯的程式 (「偵錯目標」)，並視需要重新導向輸入/輸出。請確保將適當的命令列選項傳遞給偵錯目標，以便偵錯工具能夠附加至它。建立並執行會附加至偵錯目標的「附加」偵錯設定。
如果您正在使用的偵錯工具擴充功能可以在 VS Code 的整合式終端機 (或外部終端機) 中執行偵錯目標，您可以嘗試將命令殼層重新導向語法 (例如 "<" 或 ">") 作為引數傳遞。

以下是 launch.json 設定範例
```
{
  "name": "launch program that reads a file from stdin",
  "type": "node",
  "request": "launch",
  "program": "program.js",
  "console": "integratedTerminal",
  "args": ["<", "in.txt"]
}
```
此方法要求 < 語法必須透過偵錯工具擴充功能傳遞，並且以未修改的形式到達整合式終端機。

複合啟動設定

啟動多個偵錯工作階段的另一種方法是使用複合啟動設定。您可以在 launch.json 檔案中的 compounds 屬性中定義複合啟動設定。

使用 configurations 屬性來列出應該平行啟動的兩個或多個啟動設定名稱。

您可以選擇性地指定一個在個別偵錯工作階段啟動之前執行的 preLaunchTask 工作。布林值旗標 stopAll 會控制手動終止其中一個工作階段是否會停止所有複合工作階段。

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Server",
      "program": "${workspaceFolder}/server.js"
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Client",
      "program": "${workspaceFolder}/client.js"
    }
  ],
  "compounds": [
    {
      "name": "Server/Client",
      "configurations": ["Server", "Client"],
      "preLaunchTask": "${defaultBuildTask}",
      "stopAll": true
    }
  ]
}

複合啟動設定也會顯示在啟動設定下拉式方塊功能表中。

偵錯伺服器程式時自動開啟 URI

開發網頁程式通常需要在網頁瀏覽器中開啟特定的 URL，以便在偵錯工具中觸發伺服器程式碼。VS Code 具有內建功能「serverReadyAction」來自動執行此工作。

以下是一個簡單的 Node.js Express 應用程式範例

var express = require('express');
var app = express();

app.get('/', function(req, res) {
  res.send('Hello World!');
});

app.listen(3000, function() {
  console.log('Example app listening on port 3000!');
});

此應用程式先為 "/" URL 安裝一個 "Hello World" 處理常式，然後開始在連接埠 3000 上接聽 HTTP 連線。系統會在偵錯主控台中公告該連接埠，通常開發人員現在會在他們的瀏覽器應用程式中輸入 https://:3000。

serverReadyAction 功能使得將結構化屬性 serverReadyAction 新增至任何啟動設定並選取要執行的「動作」成為可能

{
  "type": "node",
  "request": "launch",
  "name": "Launch Program",
  "program": "${workspaceFolder}/app.js",

  "serverReadyAction": {
    "pattern": "listening on port ([0-9]+)",
    "uriFormat": "https://:%s",
    "action": "openExternally"
  }
}

在這裡，pattern 屬性描述了用於比對宣告連接埠之程式輸出字串的常規表示式。連接埠號碼的模式被放在括號中，以便它可作為常規表示式擷取群組使用。在此範例中，我們僅擷取連接埠號碼，但也可以擷取完整的 URI。

uriFormat 屬性描述了如何將連接埠號碼轉換為 URI。第一個 %s 會被比對模式的第一個擷取群組所取代。

接著，產生的 URI 會使用針對該 URI 配置的標準應用程式，在 VS Code 外部 (「外部」) 開啟。

透過 Microsoft Edge 或 Chrome 觸發偵錯

或者，可以將 action 設定為 debugWithEdge 或 debugWithChrome。在此模式下，可以新增一個會傳遞給 Chrome 或 Microsoft Edge 偵錯工作階段的 webRoot 屬性。

為了簡化一些步驟，大部分屬性都是選擇性的，且我們使用下列的後援值

pattern："listening on.* (https?://\\S+|[0-9]+)"，其可用來比對常用訊息「listening on port 3000」或「Now listening on: https://:5001」。
uriFormat："https://:%s"
webRoot："${workspaceFolder}"

觸發任意的啟動設定

在某些情況下，您可能需要為瀏覽器偵錯工作階段設定更多選項，或是完全使用不同的偵錯工具。您可以將 action 設定為 startDebugging，並將 name 屬性設定為當 pattern 符合時要啟動的啟動設定名稱，藉此達成此目的。

具名啟動設定必須與包含 serverReadyAction 的啟動設定位於相同的檔案或資料夾中。

以下是 serverReadyAction 功能的實際運作情形

後續步驟

工作 (Tasks) - 描述如何使用 Gulp、Grunt 和 Jake 執行工作，以及如何顯示錯誤與警告。
變數參考 - 描述 VS Code 中可用的變數。

常見問題

最常見的問題是您尚未設定 launch.json，或者該檔案中存在語法錯誤。或者，您可能需要開啟一個資料夾，因為無資料夾偵錯不支援啟動設定。

7/29/2026