参加你附近的 ，了解 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