在 VS Code 中进行浏览器调试

Visual Studio Code 内置了适用于 Edge 和 Chrome 的调试器。有几种方法可以开始使用它。

使用打开链接 (Open Link) 命令调试 URL。
在 JavaScript 调试终端中点击链接。
使用启动配置来启动带有您的应用程序的浏览器。

您也可以在 VS Code 的内置浏览器中调试 Web 应用程序，而无需启动外部浏览器。

我们还提供了更详细的入门指南，涵盖 React、Angular 和 Vue，以及其他调试方案 (Recipes)。

打开链接命令

调试网页最简单的方法是通过命令面板（⇧⌘P (Windows, Linux Ctrl+Shift+P)）中的 Debug: Open Link 命令。运行此命令时，系统会提示您输入要打开的 URL，调试器便会附加到该页面。

Using the Open Link command to attach to a URL

如果您的默认浏览器是 Edge，VS Code 将使用它来打开页面。否则，它会尝试在您的系统上查找 Chrome 的安装路径。

启动配置

启动配置是 VS Code 中设置调试的传统方式，它为您运行复杂的应用程序提供了最大的灵活性。

在本节中，我们将更详细地介绍高级调试场景的配置和功能。Node.js 关于跳过外部代码的说明也适用于基于浏览器的调试。

注意：如果您刚开始使用 VS Code，可以在调试 (Debugging) 主题中了解通用的调试功能和如何创建 launch.json 配置文件。

启动浏览器

在大多数情况下，您需要启动一个新的浏览器实例来调试您的网页或文件。为此，您可以创建一个名为 .vscode/launch.json 的文件，内容如下：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "msedge",
      "request": "launch",
      "name": "Launch my cool app",
      "url": "https://:8000"
    }
  ]
}

当您按下 F5 或点击“运行和调试”视图中的启动按钮时，https://:8000 将以调试模式打开。如果您想使用 Chrome 而不是 Edge，请将 msedge 替换为 chrome。

要在不打开外部浏览器的情况下在 VS Code 内部进行调试，请将类型 (type) 设置为 editor-browser。了解更多关于在内置浏览器中调试的信息。

您还可以调试单个文件而不运行服务器，例如：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "msedge",
      "request": "launch",
      "name": "Launch hello.html",
      "file": "${workspaceFolder}/hello.html"
    }
  ]
}

附加到浏览器

要附加到正在运行的浏览器，需要以特殊的调试模式启动它。您可以使用以下命令执行此操作，并将 edge.exe 替换为您 Edge 或 Chrome 二进制文件的路径：

edge.exe --remote-debugging-port=9222 --user-data-dir=remote-debug-profile

设置 --remote-debugging-port 告诉浏览器在该端口上侦听调试连接。设置一个单独的 --user-data-dir 会强制打开浏览器的一个新实例；如果不设置此标志，该命令将打开已运行浏览器的窗口，而不会进入调试模式。

接下来，在 vscode/launch.json 文件中添加一个新的部分，如下所示：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "msedge",
      "request": "attach",
      "name": "Attach to browser",
      "port": 9222
    }
  ]
}

现在，您可以按下 F5 或点击“运行和调试”视图中的启动按钮来附加到正在运行的浏览器。您甚至可以添加一个 address 属性来调试在另一台机器上运行的浏览器。

启动配置属性

调试配置存储在工作区 .vscode 文件夹下的 launch.json 文件中。关于调试配置文件的创建和使用介绍，请参阅通用的调试 (Debugging) 文章。您可以选择“启动 (launch)”一个带有您的应用程序的浏览器，或者“附加 (attach)”到您已以调试模式启动的现有浏览器。

以下是特定于浏览器调试的常见 launch.json 属性参考。您可以在 vscode-js-debug 选项文档中查看完整的选项集。

webRoot - 源代码的根目录。通常且默认情况下，webRoot 是您的工作区文件夹。此选项用于源映射 (sourcemap) 解析。
outFiles - 用于定位生成的 JavaScript 文件的通配符模式 (glob patterns) 数组。请参阅源映射 (Source maps) 部分。
smartStep - 尝试自动跳过未映射到源文件的源代码。请参阅智能步进 (Smart stepping) 部分。
skipFiles - 自动跳过被这些通配符模式覆盖的文件。请参阅跳过不感兴趣的代码部分。
trace - 启用诊断输出。

这些属性仅适用于请求类型为 launch 的启动配置：

url - 启动浏览器时自动打开的 URL。
runtimeExecutable - 可执行浏览器的绝对路径，或者要使用的浏览器版本。有效版本包括 stable（默认）、canary、beta 和 dev。
runtimeArgs - 启动浏览器时传入的可选参数。

这些属性仅适用于请求类型为 attach 的启动配置：

url - 如果提供，VS Code 将附加到具有此 URL 的标签页。如果不提供，它将附加到所有浏览器标签页。
port - 用于远程调试浏览器的端口，需与启动浏览器时使用的 --remote-debugging-port 匹配。请参阅附加到浏览器部分。
address - 被调试浏览器正在侦听的 IP 地址或主机名。请参阅附加到浏览器部分。

WebAssembly 调试

浏览器中的 WebAssembly 调试与 Node.js 相同，在此处阅读有关 WebAssembly 调试的更多信息。

源映射 (Source Maps)

VS Code 中的 JavaScript 调试器支持源映射 (source maps)，允许调试转换后的代码。例如，TypeScript 代码被编译为 JavaScript，许多 Web 应用程序将所有 JavaScript 文件捆绑在一起。源映射有助于调试器找出如何映射您的原始代码与浏览器中运行的代码之间的关系。

大多数用于构建 Web 应用程序的现代工具都可以直接使用。如果不行，我们关于 Node.js 中的源映射的部分也提供了适用于浏览器调试的指南。

加载源映射

每个 JavaScript 文件都可以通过 URL 或相对路径引用源映射。在处理 Web 应用程序时，您需要确保该 URL 是在 VS Code 中运行的调试器可以访问的。如果无法访问，您将在调试控制台 (Debug Console) 中看到错误，解释哪些源映射加载失败及其原因。

如果无法直接访问，VS Code 将尝试使用浏览器的网络堆栈来请求源映射。这使得浏览器中的任何身份验证状态或网络设置都可以应用于该请求。例如，如果您的源映射位于受 Cookie 身份验证保护的位置，则仅当浏览器会话具有必要的 Cookie 时，VS Code 才能加载它们。

焦点模拟

当您调试 Web 应用程序并将焦点切换到 VS Code 时，浏览器页面会失去焦点。这会导致 :focus CSS 样式消失，document.hasFocus() 返回 false，并且焦点事件处理程序停止按预期触发。

在浏览器调试会话期间，“运行和调试”视图中的调试选项 (Debug Options) 面板提供了一个模拟焦点页面 (Emulate a focused page) 选项。启用此选项后，即使 VS Code 位于前台，页面也会表现得好像它仍具有焦点一样。此设置在调试会话中保持不变。

后续步骤

调试 (Debugging) - 了解通用的 VS Code 调试功能。
调试方案 (Debugging Recipes) - 为您喜欢的平台设置调试。

4/8/2026