Visual Studio Code 调试配置

Name: Visual Studio Code
Author: Microsoft

对于复杂的调试场景或应用，你需要创建一个launch.json文件以指定调试器配置。例如，指定应用入口点、附加到正在运行的应用程序，或设置环境变量。

想了解更多关于VS Code调试的内容，请参见Visual Studio Code中的调试。

提示

VS Code 中的 Copilot 可以帮助你创建项目的启动配置。获取更多关于用Copilot生成启动配置的信息。

发射配置

对于简单的应用程序或调试场景，你可以在没有特定调试配置的情况下运行和调试程序。使用F5键，VS代码会尝试运行你当前正在使用的文件。

不过，对于大多数调试场景，你需要创建一个调试配置（启动配置）。例如，要指定应用入口点，可以附加到正在运行的应用程序，或设置环境变量。创建启动配置文件也很有帮助，因为它允许你配置并保存调试设置细节。

VS Code 将调试配置信息存储在launch.json文件位于.vscode在你的工作区文件夹（项目根目录），或者在用户设置或工作区设置里。

以下摘录描述了调试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文件：

在运行和调试视图中选择创建launch.json文件。
VS Code 尝试检测你的调试环境。如果无法实现，你可以手动选择：

基于所选调试环境，VS Code 在launch.json档案。
在资源管理器视图（⇧⌘E（Windows，Linux Ctrl+Shift+E））中，注意 VS Code 创建了.vscode文件夹并添加了launch.json文件存档到你的工作区。

你现在可以编辑launch.json文件以添加更多配置或修改现有配置。

添加配置到 launch.json

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

点击添加配置按钮，然后选择一个片段来添加预定义的配置。
如果你的光标位于配置数组内，可以使用IntelliSense。
选择“运行>添加配置”菜单选项。

启动json建议

用AI生成发射配置

通过 VS Code 中的 Copilot，你可以加快为项目创建启动配置的过程。使用 Copilot 生成发射配置：

用⌃⌘I（Windows，Linux Ctrl+Alt+I）打开聊天视图，或在标题栏的副驾驶菜单中选择打开聊天。
这时/startDebugging聊天提示生成调试配置。

或者，你也可以输入自定义提示，比如为 Express 应用 #codebase 生成调试配置。

如果你的工作区有不同语言的文件，这会很有用。

注释
该#codebase聊天变量能让Copilot了解你的项目背景，帮助它生成更准确的响应。
应用建议配置，然后开始调试。

启动调试会话时会有一个启动配置

启动调试会话时要启动启动配置：

在运行和调试视图中的配置下拉菜单中选择名为“启动程序”的配置。

可用配置列表与launch.json档案。
用F5开始调试，或者在运行和调试视图中选择开始调试（播放图标）。

或者，你可以通过命令面板（⇧⌘P（Windows，Linux Ctrl+Shift+P））筛选调试：选择并开始调试或输入“调试”然后选择你想调试的配置。

发射与附着配置

在 VS Code 中，有两种核心调试模式：启动和附加，分别处理两个不同的工作流程和开发者分段。根据你的工作流程，判断哪种配置适合你的项目可能会让人困惑。

如果你来自浏览器开发者工具的背景，可能不习惯“从工具启动”，因为你的浏览器实例已经打开了。当你打开 DevTools 时，你只是把 DevTools 附加到打开的浏览器标签页上。另一方面，如果你来自服务器或桌面背景，通常会让编辑器帮你启动进程，编辑器会自动将调试器附加到新启动的进程上。

解释启动和连接的最好方式是把启动配置看作是在VS Code绑定前以调试模式启动应用的配方，而附件配置则是将VS Code调试器连接到已经运行的应用或进程的配方。

VS Code 调试器通常支持在调试模式下启动程序，或在调试模式下附加到已运行的程序。根据请求的不同（附着或发射），需要不同的属性，以及VS Code。launch.json认可和建议应该能帮到你。

Launch.json属性

有很多launch.json属性帮助支持不同的调试器和调试场景。在为 类型属性。启动配置中可用的属性因调试器而异。

启动json建议

一个属性适用于某个调试器，并不会自动适用于其他调试器。如果你在启动配置中看到红色曲线，将鼠标悬停在它们上方，了解问题所在，并在启动调试前尝试修复。

以下属性是每种发射配置的必备条件：

类型- 用于该启动配置的调试器类型。每个安装的调试扩展都会引入一个类型：节点例如，内置的节点调试器，或者PHP以及走用于PHP和Go扩展。
请求- 该发射配置的请求类型。目前，
发射
- 在VS代码中打开
- 在VS Code Insiders中开放
以及附着是支持的。
名称- 在调试启动配置下拉菜单中出现的友好读者名称。

以下是所有发射配置可用的一些可选属性：

呈现- 使用顺序,集团，和隐藏属性呈现你可以在调试配置下拉菜单和调试快速选择中排序、分组和隐藏配置和复合物。
预启动任务- 在调试会话开始前启动任务，将该属性设置为tasks.json中指定的任务标签（在工作区的.vscode文件夹）。或者，可以设置为${defaultBuildTask}使用默认的建造任务。
postDebugTask- 要在调试会话的最后启动任务，将该属性设置为tasks.json中指定的任务名称（在工作区的.vscode文件夹）。
internalConsoleOptions- 该属性控制调试控制台面板在调试会话中的可见性。
debugServer - 仅限调试扩展作者：该属性允许您连接到指定的端口，而无需启动调试适配器。
服务器准备行动- 如果你想在调试程序向调试控制台或集成终端输出特定消息时，在浏览器中打开一个URL。详情请参见下方“调试服务器程序时自动打开URI”部分。

许多调试器支持以下一些属性：

节目- 执行文件或在调试器启动时运行的文件
args- 传递给程序调试的参数
环境- 环境变量（值无效可以用来“解定义”变量）
envFile- 带环境变量的dotenv文件路径
慢性消耗病- 当前工作目录，用于查找依赖和其他文件
港口- 连接运行进程时的端口
停止进入- 程序启动时立即中断
控制台- 使用哪种控制台，例如，内部控制台,integratedTerminal，或者外部终端

变量替换

VS Code 允许常用路径和其他值作为变量，并支持字符串中的变量替换launch.json.这意味着你在调试配置中不必使用绝对路径。例如，${workspaceFolder}给出工作区文件夹的根路径，${file}在活动编辑器中打开的文件，${env：Name}环境变量“Name”。

你可以在变量参考中查看预定义变量的完整列表，或者在launch.json字符串属性。

{
  "type": "node",
  "request": "launch",
  "name": "Launch Program",
  "program": "${workspaceFolder}/app.js",
  "cwd": "${workspaceFolder}",
  "args": ["${env:USERNAME}"]
}

平台专属属性

VS Code 支持定义依赖于调试器运行的作系统的调试配置设置（例如，要传递给程序的参数）。要做到这一点，可以在launch.json文件并指定该字面量内对应的属性。

以下示例展示了如何通过“ARGS”在Windows上与程序有不同的不同：

{
  "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，“Linux”对于Linux，以及“OSX”macOS版。作系统中定义的属性覆盖了全局范围内定义的属性。

该类型财产不能放置在站台特定区域内，因为类型在远程调试场景中间接决定了平台，这会导致循环依赖。

在以下示例中，调试程序始终在进入时停止，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": {
    "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档案。

使用该配置属性以列出两个或多个应并行启动的启动配置名称。

可选地，指定一个预启动任务在各个调试会话开始之前执行的任务。布尔旗停止所有控制手动终止一个会话是否会停止所有复合会话。

{
  "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!');
});

该应用程序首先安装“Hello World”处理程序，用于“/”的URL，然后开始监听端口3000上的HTTP连接。移植将在调试控制台中宣布，通常开发者会输入http://localhost:3000进入他们的浏览器应用。

serverReadyAction 功能使得添加结构化属性成为可能服务器准备行动对任意启动配置并选择要执行的“动作”：

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

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

这里图案属性描述了匹配程序输出字符串的正则表达式，该字符串用于宣布端口。端口编号的模式被括号标注，以便作为正则表达式捕获组使用。在这个例子中，我们只提取端口号，但也可以提取完整的URI。

该uri格式property 描述了端口号如何转换为 URI。第一%s被匹配图案的第一个捕获群替代。

生成的URI随后在VS Code之外（“外部”）打开，并根据该URI方案配置了标准应用程序。

通过 Microsoft Edge 或 Chrome 触发调试

或者，行动可以设置为debugWithEdge或debugWithChrome.在此模式下，一个web根可以添加属性，传递给 Chrome 或 Microsoft Edge 调试会话。

为了简化说明，大多数属性是可选的，我们使用以下备用值：

模式：“继续听。* （https？@\\S+|[0-9]+)"这与常用的“监听端口3000”或“正在监听：https://localhost:5001”相符。
uri格式：“http：//localhost：%s”
webRoot：“${workspaceFolder}”

触发任意启动配置

在某些情况下，你可能需要为浏览器调试会话配置更多选项，或者使用完全不同的调试器。你可以通过设置来实现行动到start调试其中名称属性设置为发射配置名称，当图案匹配。

指定的启动配置必须与包含服务器准备行动.

以下是serverReadyAction功能的实际作：

下一步

任务——描述如何与Gulp、Grunt和Jake一起运行任务，以及如何显示错误和警告。
变量参考——描述VS代码中可用的变量。

常见问题

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