调试

Visual Studio Code 的关键功能之一是其强大的调试支持。VS Code 的内置调试器有助于加速你的编辑、编译和调试循环。

用户界面

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

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

调试器扩展

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

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

以下是包含调试支持的几个常用扩展

提示：上面显示的扩展是动态查询的。选择上面的扩展磁贴以阅读描述和评论，以决定哪个扩展最适合你。

开始调试

以下文档基于内置的 Node.js 调试器，但大多数概念和功能也适用于其他调试器。

在阅读有关调试的内容之前，最好先创建一个示例 Node.js 应用程序。你可以按照 Node.js 演练来安装 Node.js 并创建一个简单的“Hello World”JavaScript 应用程序 (app.js)。设置好简单的应用程序后，此页面将引导你了解 VS Code 的调试功能。

运行和调试视图

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

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

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

运行菜单

顶级的运行菜单包含最常见的运行和调试命令

启动配置

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

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

要创建 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 文件添加到了你的工作区。

注意：即使你没有在 VS Code 中打开文件夹，也可以调试一个简单的应用程序，但是无法管理启动配置并设置高级调试。如果你没有打开文件夹，VS Code 状态栏会显示为紫色。

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

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

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

启动与附加配置

在 VS Code 中，有两种核心调试模式：启动和附加，它们处理两种不同的工作流和开发人员群体。根据你的工作流，你可能会对哪种类型的配置适合你的项目感到困惑。

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

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

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

添加新配置

要向现有的 launch.json 添加新配置，请使用以下方法之一：

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

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

要启动调试会话，首先在“运行和调试”视图中使用“配置下拉列表”选择名为“启动程序”的配置。设置好启动配置后，使用 F5 启动调试会话。

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

调试会话开始后，将显示“调试控制台”面板并显示调试输出，并且状态栏的颜色会发生变化（默认主题为橙色）。

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

调试操作

调试会话开始后，“调试工具栏”将显示在窗口顶部。

提示：使用设置 debug.toolBarLocation 来控制调试工具栏的位置。它可以是默认的 floating，docked 到“运行和调试”视图，或者 hidden。浮动调试工具栏可以水平拖动，也可以向下拖动到编辑器区域（距离顶部边缘一定距离）。

运行模式

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

提示：“运行”操作始终可用，但并非所有调试器扩展都支持“运行”。在这种情况下，“运行”将与“调试”相同。

断点

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

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

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

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

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

日志点

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

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

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

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

注意：VS Code 的内置 Node.js 调试器支持日志点，但其他调试扩展可以实现日志点。Python 和 Java 扩展，例如，支持日志点。

数据检查

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

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

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

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

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）或在调试会话期间通过上下文菜单来设置内联断点。内联断点在编辑器中内联显示。

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

函数断点

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

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

数据断点

如果调试器支持数据断点，则可以从“变量”视图的上下文菜单中设置它们。“在值更改/读取/访问时中断”命令添加一个数据断点，该断点在底层变量的值更改/读取/访问时命中。数据断点在“断点”部分中以红色六边形显示。

调试控制台 REPL

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

在您按 Enter 后，表达式会被求值，“调试控制台”REPL 会在您键入时显示建议。如果您需要输入多行，请在行之间使用 Shift+Enter，然后使用 Enter 发送所有行进行求值。

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

注意：您必须处于正在运行的调试会话中才能使用“调试控制台”REPL。

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

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

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

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

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 就会切换到多目标模式

• 各个会话现在在“调用堆栈”视图中显示为顶层元素。

  

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

  

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

复合启动配置

启动多个调试会话的另一种方法是使用复合启动配置。您可以在 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 添加到任何启动配置，并选择要执行的“操作”

{
  "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："https://127.0.0.1:%s"
• webRoot："${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 中进行调试。

要了解通过 VS Code 扩展对其他编程语言的调试支持，请访问

• C++
• Python
• Java

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

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

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

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

常见问题

支持哪些调试场景？

VS Code 开箱即用地支持在 Linux、macOS 和 Windows 上调试基于 Node.js 的应用程序。许多其他场景可以通过 Marketplace 中提供的 VS Code 扩展进行支持。

我在“运行和调试”视图下拉菜单中没有看到任何启动配置。哪里出错了？

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