调试

Visual Studio Code 的主要功能之一是其出色的调试支持。VS Code 的内置调试器有助于加速您的编辑、编译和调试循环。Visual Studio Marketplace 提供了各种各样的调试扩展，为 VS Code 添加对其他语言和运行时的调试支持。

本文介绍了 VS Code 的调试功能，以及如何开始在 VS Code 中进行调试。您还将学习如何使用 VS Code 中的 Copilot 来加速设置调试配置和启动调试会话。

以下视频演示了如何在 VS Code 中开始调试。

用户界面

下图显示了调试用户界面的主要组件

1. 运行和调试视图：显示与运行、调试和管理调试配置设置相关的所有信息。
2. 调试工具栏：包含最常用的调试操作按钮。
3. 调试控制台：允许查看和与调试器中运行的代码的输出进行交互。
4. 调试侧边栏：在调试会话期间，允许您与调用堆栈、断点、变量和监视变量进行交互。
5. 运行 菜单：包含最常用的运行和调试命令。

运行和调试视图

要打开 运行和调试 视图，请在 VS Code 侧边的 活动栏 中选择 运行和调试 图标。您也可以使用键盘快捷键 ⇧⌘D（Windows、Linux Ctrl+Shift+D）。

运行和调试 视图显示与运行和调试相关的所有信息，并在顶部栏中包含调试命令和配置设置。

如果运行和调试尚未配置（尚未创建 launch.json），VS Code 将显示“运行”启动视图。

调试操作

调试会话开始后，调试工具栏 将出现在窗口顶部。

调试器扩展

VS Code 内置了对 Node.js 运行时的调试支持，并且可以调试 JavaScript、TypeScript 或任何其他转译为 JavaScript 的语言。

对于调试其他语言和运行时（包括 PHP、Ruby、Go、C#、Python、C++、PowerShell 和 许多其他语言），请在 Visual Studio Marketplace 中查找 Debuggers 扩展，或在顶层“运行”菜单中选择 安装其他调试器。

以下是一些流行的扩展，其中包括调试支持

开始调试

1. 为您的语言和运行时安装 调试器扩展。

   VS Code 内置了对调试 Node.js、JavaScript 和 TypeScript 的支持。

2. 可选地，配置 launch.json 启动配置。

   对于简单的应用程序，VS Code 将尝试调试您当前活动的文件，而无需启动配置。但是，对于大多数调试场景，创建启动配置文件是必要的。

   提示

   Copilot 可以帮助您创建启动配置。打开 Copilot Chat 并输入 /startDebugging 聊天提示，Copilot 将为您生成启动配置。或者，输入类似 generate a launch config for a django app #codebase 的提示。

3. 按 F5，或按 运行和调试 视图中的绿色播放按钮以启动调试会话。

   提示

   Copilot 可以通过使用 copilot-debug 终端命令帮助您设置和启动调试会话。输入 copilot-debug，后跟运行应用程序的命令，以启动调试会话。例如，输入 copilot-debug node /bin/www 或 copilot-debug python app.py 以启动 Node.js 或 Python 应用程序的调试会话。

运行模式

除了调试程序之外，VS Code 还支持运行程序。调试：不调试启动 操作通过 ⌃F5（Windows、Linux Ctrl+F5） 触发，并使用当前选定的启动配置。许多启动配置属性在“运行”模式下都受支持。VS Code 在程序运行时维护调试会话，按下 停止 按钮会终止程序。

启动配置

要在 VS Code 中运行或调试简单的应用程序，请在“调试”启动视图中选择 运行和调试 或按 F5，VS Code 将尝试运行您当前活动的文件。

但是，对于大多数调试场景，创建启动配置文件是有益的，因为它允许您配置和保存调试设置详细信息。VS Code 将调试配置信息保存在工作区（项目根文件夹）的 .vscode 文件夹中的 launch.json 文件中，或保存在您的用户设置或工作区设置中。

要创建 launch.json 文件，请在“运行”启动视图中选择 创建 launch.json 文件。

VS Code 将尝试自动检测您的调试环境，但如果失败，您可以手动选择它

这是为 Node.js 调试生成的启动配置

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

如果您返回到文件资源管理器视图 (⇧⌘E（Windows、Linux Ctrl+Shift+E）)，您将看到 VS Code 创建了一个 .vscode 文件夹，并将 launch.json 文件添加到了您的工作区。

请注意，启动配置中可用的属性因调试器而异。您可以使用 IntelliSense 建议 (⌃Space（Windows、Linux Ctrl+Space）) 来查找特定调试器存在的属性。悬停帮助也适用于所有属性。

不要假设一个调试器可用的属性也自动适用于其他调试器。如果您在启动配置中看到红色波浪线，请将鼠标悬停在它们上面以了解问题所在，并在启动调试会话之前尝试修复它们。

查看所有自动生成的值，并确保它们对您的项目和调试环境有意义。

使用 AI 生成启动配置

借助 VS Code 中的 Copilot，您可以加速为您的项目创建启动配置的过程。要使用 Copilot 生成启动配置：

1. 使用 ⌃⌘I（Windows、Linux Ctrl+Alt+I） 打开“聊天”视图，或从标题栏中的 Copilot 菜单中选择 打开聊天。

2. 输入 /startDebugging 聊天提示以生成调试配置。

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

   如果您的工作区中有不同语言的文件，这将非常有用。

   注意

   #codebase 聊天变量为 Copilot 提供了您的项目上下文，这有助于它生成更准确的响应。

3. 应用建议的配置，然后开始调试。

启动与附加配置

在 VS Code 中，有两种核心调试模式：启动 和 附加，它们处理两种不同的工作流程和开发者群体。根据您的工作流程，可能很难知道哪种类型的配置适合您的项目。

如果您来自浏览器开发者工具背景，您可能不习惯“从您的工具启动”，因为您的浏览器实例已经打开。当您打开 DevTools 时，您只是将 DevTools 附加 到您打开的浏览器选项卡。另一方面，如果您来自服务器或桌面背景，您的编辑器为您 启动 您的进程，并且您的编辑器自动将其调试器附加到新启动的进程，这是非常正常的。

解释 启动 和 附加 之间差异的最佳方法是将 启动 配置视为如何在 VS Code 附加到应用程序 之前 以调试模式启动应用程序的配方，而 附加 配置是如何将 VS Code 的调试器连接到 已经 运行的应用程序或进程的配方。

VS Code 调试器通常支持以调试模式启动程序或附加到已在调试模式下运行的程序。根据请求（attach 或 launch），需要不同的属性，VS Code 的 launch.json 验证和建议应该对此有所帮助。

添加新配置

要将新配置添加到现有的 launch.json，请使用以下技术之一：

• 如果您的光标位于 configurations 数组内，请使用 IntelliSense。
• 按 添加配置 按钮以在数组的开头调用代码片段 IntelliSense。
• 在“运行”菜单中选择 添加配置 选项。

VS Code 还支持用于同时启动多个配置的复合启动配置；有关更多详细信息，请阅读此部分。

为了启动调试会话，首先使用 运行和调试 视图中的 配置下拉列表 选择名为 Launch Program 的配置。设置好启动配置后，使用 F5 启动调试会话。

或者，您可以通过 命令面板 (⇧⌘P（Windows、Linux Ctrl+Shift+P）) 运行您的配置，方法是筛选 调试：选择并启动调试 或键入 'debug ' 并选择您要调试的配置。

调试会话启动后，将显示 调试控制台 面板并显示调试输出，并且状态栏会更改颜色（默认颜色主题为橙色）

此外，调试状态 出现在状态栏中，显示活动调试配置。通过选择调试状态，用户可以更改活动启动配置并开始调试，而无需打开 运行和调试 视图。

断点

可以通过单击 编辑器边距 或在当前行使用 F9 来切换断点。更精细的断点控制（启用/禁用/重新应用）可以在 运行和调试 视图的 断点 部分完成。

• 编辑器边距中的断点通常显示为红色实心圆圈。
• 禁用的断点具有灰色实心圆圈。
• 当调试会话开始时，无法在调试器中注册的断点将变为灰色空心圆圈。如果在没有实时编辑支持的调试会话运行时编辑了源代码，也可能发生同样的情况。

如果调试器支持在不同类型的错误或异常处中断，则这些错误或异常也将在 断点 视图中可用。

重新应用所有断点 命令将所有断点再次设置为其原始位置。如果您的调试环境是“惰性的”并且将断点“错放”在尚未执行的源代码中，这将非常有用。

可选地，可以通过启用设置 debug.showBreakpointsInOverviewRuler 在编辑器的概览标尺中显示断点

日志点

日志点是断点的一种变体，它不会“中断”到调试器中，而是将消息记录到调试控制台。日志点使您可以在调试时注入日志记录，而无需修改源代码。当您调试无法暂停或停止的生产服务器时，它们尤其有用。日志点还可以通过不必在代码中添加或删除日志语句来帮助您节省时间。

日志点由“菱形”图标表示。日志消息是纯文本，但可以包含要在花括号 ('{}') 内计算的表达式。

使用左侧编辑器装订线上下文菜单中的 添加日志点 命令，或使用 调试：添加日志点... 命令添加日志点。您还可以配置设置 debug.gutterMiddleClickAction 以在编辑器装订线中按下鼠标中键时切换日志点。

与常规断点一样，日志点可以启用或禁用，也可以通过条件和/或命中计数来控制。

数据检查

可以在 运行和调试 视图的 变量 部分中检查变量，或将鼠标悬停在编辑器中的源代码上。变量值和表达式求值相对于 调用堆栈 部分中选定的堆栈帧。

可以使用变量上下文菜单中的 设置值 操作修改变量值。此外，您可以使用 复制值 操作复制变量的值，或使用 复制为表达式 操作复制访问变量的表达式。

变量和表达式也可以在 运行和调试 视图的 监视 部分中求值和监视。

可以通过在焦点位于 变量 部分时键入来筛选变量名和值。

Launch.json 属性

有许多 launch.json 属性可帮助支持不同的调试器和调试场景。如上所述，一旦您为 type 属性指定了值，您可以使用 IntelliSense (⌃Space（Windows、Linux Ctrl+Space）) 查看可用属性的列表。

以下属性对于每个启动配置都是必需的：

• 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}"]
}

特定于平台的属性

Launch.json 支持定义依赖于调试器运行所在的操作系统的值（例如，要传递给程序的参数）。为此，请将特定于平台的文字放入 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
      }
    }
  ]
}

全局启动配置

VS Code 支持在您的用户设置中添加 "launch" 对象。然后，此 "launch" 配置将在您的工作区之间共享。例如：

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

高级断点主题

条件断点

VS Code 调试的一项强大功能是能够设置基于表达式、命中计数或两者组合的条件。

• 表达式条件：每当表达式的计算结果为 true 时，将命中该断点。
• 命中计数：命中计数 控制断点需要被命中多少次才能中断执行。命中计数是否被尊重，以及表达式的确切语法，可能因调试器扩展而异。

您可以在创建源断点时（使用 添加条件断点 操作）或修改现有断点时（使用 编辑条件 操作）添加条件和/或命中计数。在这两种情况下，都会打开一个带有下拉菜单的内联文本框，您可以在其中输入表达式

条件和命中计数编辑支持也适用于函数和异常断点。您可以从上下文菜单或新的内联 编辑条件 操作启动条件编辑。

断点 视图中的条件编辑示例：

如果调试器不支持条件断点，则 添加条件断点 和 编辑条件 操作不可用。

触发断点

触发断点是一种断点，它在另一个断点被命中后自动启用。当诊断仅在特定先决条件之后才发生的代码中的故障情况时，它们非常有用。

可以通过右键单击字形边距，选择 添加触发断点，然后选择哪个其他断点启用该断点来设置触发断点。

触发断点适用于所有语言，条件断点也可以用作触发器。

内联断点

仅当执行到达与内联断点关联的列时，才会命中内联断点。当调试包含单行多条语句的压缩代码时，这尤其有用。

可以使用 ⇧F9 (Windows, Linux Shift+F9) 或在调试会话期间通过上下文菜单设置内联断点。内联断点在编辑器中以内联方式显示。

内联断点也可以有条件。可以通过编辑器左侧边距中的上下文菜单编辑行上的多个断点。

函数断点

调试器可以支持通过指定函数名称来创建断点，而不是直接在源代码中放置断点。这在源代码不可用但函数名称已知的情况下非常有用。

函数断点通过按 BREAKPOINTS（断点）部分标题中的 + 按钮并输入函数名称来创建。函数断点在 BREAKPOINTS（断点）部分中以红色三角形显示。

数据断点

如果调试器支持数据断点，则可以从 VARIABLES（变量）视图中的上下文菜单设置数据断点。Break on Value Change/Read/Access（值更改/读取/访问时中断）命令添加一个数据断点，当底层变量的值更改/被读取/被访问时，将命中该断点。数据断点在 BREAKPOINTS（断点）部分中以红色六边形显示。

调试控制台 REPL

可以使用 Debug Console（调试控制台）REPL (读取-求值-打印循环) 功能评估表达式。要打开调试控制台，请使用调试窗格顶部的 Debug Console（调试控制台）操作，或使用 View: Debug Console（视图：调试控制台）命令 (⇧⌘Y (Windows, Linux Ctrl+Shift+Y))。

表达式在您按下 Enter 键后进行评估，并且调试控制台 REPL 在您键入时显示建议。如果您需要输入多行，请在行之间使用 Shift+Enter，然后使用 Enter 发送所有行进行评估。

调试控制台输入使用活动编辑器的模式，这意味着调试控制台输入支持语法着色、缩进、引号自动关闭和其他语言功能。

重定向到/从调试目标的输入/输出

重定向输入/输出是调试器/运行时特定的，因此 VS Code 没有适用于所有调试器的内置解决方案。

以下是您可能想要考虑的两种方法

1. 在终端或命令提示符中手动启动要调试的程序（“调试目标”），并根据需要重定向输入/输出。确保将适当的命令行选项传递给调试目标，以便调试器可以附加到它。创建并运行一个“attach”（附加）调试配置，该配置附加到调试目标。

2. 如果您使用的调试器扩展可以在 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"]
   }
   

   此方法要求“<”语法通过调试器扩展传递，并在集成终端中保持未修改状态。

多目标调试

对于涉及多个进程（例如，客户端和服务器）的复杂场景，VS Code 支持多目标调试。在启动第一个调试会话后，您可以启动另一个调试会话。一旦第二个会话启动并运行，VS Code UI 将切换到多目标模式

• 各个会话现在在 CALL STACK（调用堆栈）视图中显示为顶层元素。

  

• 调试工具栏显示当前活动会话（所有其他会话都可以在下拉菜单中找到）。

  

• 调试操作（例如，调试工具栏中的所有操作）在活动会话上执行。可以通过使用调试工具栏中的下拉菜单或在 CALL STACK（调用堆栈）视图中选择不同的元素来更改活动会话。

复合启动配置

启动多个调试会话的另一种方法是使用复合启动配置。您可以在 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
    }
  ]
}

复合启动配置显示在启动配置下拉菜单中。

远程调试

VS Code 不支持跨所有语言的内置远程调试。远程调试是您正在使用的调试扩展的一项功能，您应该查阅 Marketplace（应用商店）中的扩展页面以获取支持和详细信息。

但是，有一个例外：VS Code 中包含的 Node.js 调试器支持远程调试。请参阅 Node.js 调试主题，了解如何配置此功能。

在调试服务器程序时自动打开 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://127.0.0.1:3000。

serverReadyAction 功能使得可以将结构化属性 serverReadyAction 添加到任何启动配置，并选择要执行的“action”（操作）

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

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

这里的 pattern 属性描述了用于匹配程序输出字符串的正则表达式，该字符串公布了端口。端口号的模式放在括号中，以便它可以作为正则表达式捕获组使用。在本例中，我们仅提取端口号，但也可以提取完整的 URI。

uriFormat 属性描述了如何将端口号转换为 URI。第一个 %s 由匹配模式的第一个捕获组替换。

然后，生成的 URI 在 VS Code 外部（“外部地”）打开，并使用为 URI 方案配置的标准应用程序。

通过 Edge 或 Chrome 触发调试

或者，可以将 action 设置为 debugWithEdge 或 debugWithChrome。在此模式下，可以添加一个 webRoot 属性，该属性将传递给 Chrome 或 Edge 调试会话。

为了简化操作，大多数属性是可选的，我们使用以下回退值

• pattern（模式）: "listening on.* (https?://\\S+|[0-9]+)"，它匹配常用的消息“listening on port 3000”或“Now listening on: https://127.0.0.1:5001”。
• uriFormat（URI 格式）: "https://127.0.0.1:%s"
• webRoot（Web 根目录）: "${workspaceFolder}"

触发任意启动配置

在某些情况下，您可能需要为浏览器调试会话配置其他选项，或完全使用不同的调试器。您可以通过将 action 设置为 startDebugging，并将 name 属性设置为在匹配 pattern 时要启动的启动配置的名称来执行此操作。

命名的启动配置必须与具有 serverReadyAction 的配置在同一文件或文件夹中。

这是 serverReadyAction 功能的实际应用

后续步骤

要了解有关 VS Code 的 Node.js 调试支持，请查看

• Node.js - 描述了 VS Code 中包含的 Node.js 调试器。
• TypeScript - Node.js 调试器也支持 TypeScript 调试。

要观看关于调试基础知识的教程，请查看此视频

• VS Code 调试入门 - 了解 VS Code 中的调试。

要了解有关 Copilot 和 VS Code 中 AI 辅助调试的更多信息

• 使用 Copilot 调试和修复问题
• Copilot 调试和修复问题速查表

要了解有关通过 VS Code 扩展对其他编程语言的调试支持

• C++
• Python
• Java

要了解有关 VS Code 的任务运行支持，请转到

• 任务 - 描述如何使用 Gulp、Grunt 和 Jake 运行任务，以及如何显示错误和警告。

要编写您自己的调试器扩展，请访问

• 调试器扩展 - 使用模拟示例来说明创建 VS Code 调试扩展所需的步骤。

常见问题

支持哪些调试场景？

基于 Node.js 的应用程序的调试在 Linux、macOS 和 Windows 上通过 VS Code 开箱即用。许多其他场景都通过 VS Code 扩展（在应用商店中提供）支持。

我在“运行和调试”视图下拉列表中看不到任何启动配置。怎么回事？

最常见的问题是您没有设置 launch.json 或该文件中存在语法错误。或者，您可能需要打开一个文件夹，因为无文件夹调试不支持启动配置。