參加你附近的 ，瞭解 VS Code 中的 AI 輔助開發。

Visual Studio Code 除錯配置

對於複雜的除錯場景或應用程式，你需要建立一個 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 檔案

  1. 在“執行和除錯”檢視中選擇建立 launch.json 檔案。

    launch configuration

  2. VS Code 會嘗試檢測你的除錯環境。如果無法檢測，你可以手動選擇

    debug environment selector

    根據所選的除錯環境，VS Code 會在 launch.json 檔案中建立一個初始配置。

  3. 在資源管理器檢視（⇧⌘E (Windows、Linux 為 Ctrl+Shift+E)）中，你會注意到 VS Code 建立了一個 .vscode 資料夾，並將 launch.json 檔案新增到了你的工作區中。

    launch.json in Explorer

你現在可以編輯 launch.json 檔案，以新增更多配置或修改現有配置。

向 launch.json 新增配置

要向現有的 launch.json 新增新配置，請使用以下方法之一

  • 按新增配置按鈕，然後選擇一個程式碼片段以新增預定義的配置。
  • 如果游標位於 configurations 陣列內，請使用 IntelliSense。
  • 選擇執行 > 新增配置選單選項。

launch json suggestions

使用 AI 生成啟動配置

藉助 VS Code 中的 Copilot，你可以加速為專案建立啟動配置的過程。要使用 Copilot 生成啟動配置

  1. 使用 ⌃⌘I (Windows、Linux 為 Ctrl+Alt+I) 開啟聊天檢視，或從標題欄的 Copilot 選單中選擇開啟聊天。

  2. 輸入 /startDebugging 聊天提示以生成除錯配置。

    或者，你也可以輸入自定義提示，例如“為 express 應用生成除錯配置 #codebase”。

    如果你的工作區中有不同語言的檔案，這會很有用。

    注意

    #codebase 聊天變數為 Copilot 提供了你專案的上下文，這有助於它生成更準確的響應。

  3. 應用建議的配置，然後開始除錯。

使用啟動配置開始除錯會話

要使用啟動配置開始除錯會話

  1. 在執行和除錯檢視中，使用配置下拉選單選擇名為啟動程式的配置。

    可用配置列表與 launch.json 檔案中的配置相匹配。

    Screenshot that shows the launch configuration dropdown.

  2. 使用 F5 開始你的除錯會話，或在執行和除錯檢視中選擇開始除錯（播放圖示）。

或者，你可以透過命令面板（⇧⌘P (Windows、Linux 為 Ctrl+Shift+P)）執行你的配置，方法是篩選Debug: Select and Start Debugging 或輸入 'debug ' 並選擇你想要除錯的配置。

啟動配置與附加配置

在 VS Code 中，有兩種核心除錯模式，啟動（Launch）和附加（Attach），它們處理兩種不同的工作流程和開發者群體。根據你的工作流程，可能很難知道哪種型別的配置適合你的專案。

如果你來自瀏覽器開發者工具的背景，你可能不習慣“從你的工具啟動”，因為你的瀏覽器例項已經開啟。當你開啟 DevTools 時，你只是將 DevTools 附加到你開啟的瀏覽器選項卡上。另一方面，如果你來自伺服器或桌面開發背景，讓你的編輯器為你啟動程序是很正常的，你的編輯器會自動將其偵錯程式附加到新啟動的程序上。

解釋啟動和附加之間區別的最佳方式是，將啟動配置視為 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 和 attach。
  • name - 顯示在除錯啟動配置下拉選單中的易於閱讀的名稱。

以下是一些可用於所有啟動配置的可選屬性

  • presentation - 使用 presentation 物件中的 order、group 和 hidden 屬性，你可以在除錯配置下拉選單和除錯快速選擇中對配置和複合配置進行排序、分組和隱藏。
  • preLaunchTask - 要在除錯會話開始前啟動一個任務，請將此屬性設定為在 tasks.json（在工作區的 .vscode 資料夾中）中指定的任務標籤。或者，可以將其設定為 ${defaultBuildTask} 以使用你的預設構建任務。
  • postDebugTask - 要在除錯會話結束時啟動一個任務，請將此屬性設定為在 tasks.json（在工作區的 .vscode 資料夾中）中指定的任務名稱。
  • internalConsoleOptions - 此屬性控制除錯會話期間除錯控制檯面板的可見性。
  • debugServer - 僅供除錯擴充套件作者使用：此屬性允許你連線到指定的埠，而不是啟動除錯介面卡。
  • serverReadyAction - 如果你希望在被除錯的程式向除錯控制檯或整合終端輸出特定訊息時，在 Web 瀏覽器中開啟一個 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
      }
    }
  ]
}

全域性啟動配置

你可以定義在所有工作區中都可用的啟動配置。要指定全域性啟動配置，請在你的 launch 使用者設定中新增一個啟動配置物件。這個 launch 配置隨後將在你的所有工作區之間共享。例如

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

將輸入/輸出重定向到/從除錯目標

輸入/輸出重定向是特定於偵錯程式或執行時的，因此 VS Code 沒有一個適用於所有偵錯程式的內建解決方案。

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

  • 在終端或命令提示符中手動啟動要除錯的程式（“除錯目標”），並根據需要重定向輸入/輸出。確保向除錯目標傳遞適當的命令列選項，以便偵錯程式可以附加到它。建立並執行一個“附加”除錯配置，該配置會附加到除錯目標。

  • 如果你使用的偵錯程式擴充套件可以在 VS Code 的整合終端（或外部終端）中執行除錯目標，你可以嘗試將 shell 重定向語法（例如，“<” 或 “>”）作為引數傳遞。

    這是一個 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

開發 Web 程式通常需要在 Web 瀏覽器中開啟一個特定的 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，並選擇要執行的“action”

{
  "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 隨後會在 VS Code 外部（“externally”）使用為該 URI 方案配置的標準應用程式開啟。

透過 Microsoft Edge 或 Chrome 觸發除錯

或者，action 可以設定為 debugWithEdge 或 debugWithChrome。在此模式下，可以新增一個 webRoot 屬性，該屬性會傳遞給 Chrome 或 Microsoft Edge 除錯會話。

為了簡化一些事情，大多數屬性都是可選的，我們使用以下備用值

  • 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 功能的實際操作

後續步驟

  • 任務 - 描述如何使用 Gulp、Grunt 和 Jake 執行任務，以及如何顯示錯誤和警告。
  • 變數參考 - 描述 VS Code 中可用的變數。

常見問題

我在“執行和除錯”檢視下拉選單中看不到任何啟動配置。出了什麼問題？

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

09/11/2025