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 檔案

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

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

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

新增設定至 launch.json

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

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

launch json suggestions

使用 AI 產生啟動設定

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

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

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

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

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

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

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

使用執行與偵錯檢視中的設定下拉式清單，選取名為 Launch Program 的設定。

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

或者，您可以透過命令選擇區 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 執行您的設定，方法是篩選偵錯：選取並開始偵錯 (Debug: Select and Start Debugging)，或輸入 'debug ' 並選取您想要偵錯的設定。

啟動 (Launch) 與附加 (Attach) 設定

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

如果您來自瀏覽器開發者工具背景，您可能不習慣「從您的工具啟動」，因為您的瀏覽器執行個體已經開啟。當您開啟 DevTools 時，您只是在附加 (attaching) DevTools 到已開啟的瀏覽器索引標籤。另一方面，如果您來自伺服器或桌面背景，讓編輯器為您啟動 (launch) 處理序，並且讓編輯器自動將其偵錯工具附加到新啟動的處理序中，是相當正常的。

解釋啟動與附加之間差異的最佳方式，是將啟動設定視為如何在 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 會間接決定平台，這將導致循環相依性。

在下列範例中，偵錯程式總是會在進入時停止 (stop on entry)，除了在 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 沒有適用於所有偵錯工具的內建解決方案。

以下是您可以考慮的兩種方法

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

以下是 launch.json 設定範例
```
{
  "name": "launch program that reads a file from stdin",
  "type": "node",
  "request": "launch",
  "program": "program.js",
  "console": "integratedTerminal",
  "args": ["<", "in.txt"]
}
```
此方法要求 < 語法必須通過偵錯工具延伸模組傳遞，並以未修改的狀態進入「整合終端機」。

複合啟動設定

啟動多個偵錯工作階段的另一種方式是使用複合 (compound) 啟動設定。您可以在 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 屬性。

為了簡化作業，大多數屬性均為選用，我們使用下列後援 (fallback) 值

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

觸發任意啟動設定

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

命名的啟動設定必須與帶有 serverReadyAction 的設定位於同一個檔案或資料夾中。

這是實際運作中的 serverReadyAction 功能

後續步驟

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

常見問題

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

4/8/2026