使用 Visual Studio Code 调试 WebView2 应用

使用 Microsoft Visual Studio Code 调试在 WebView2 控件中运行的脚本。

详细内容：

• 简介
• 创建launch.json文件
  • 使用注册表值
  • 传入的命令行 URL 参数
• 调试代码
• 目标 WebView2 调试
  • 无法同时调试两个 WebView2 控件
• 调试正在运行的进程
  • 使用环境变量
• 调试跟踪选项
• 调试 Office 加载项
• 调试 WebView2 WinUI 2 (UWP) 应用
• 具有 WebResourceRequested 事件或虚拟主机名映射的源映射
• 调试程序疑难解答
  • 不停在断点
  • 无法附加到正在运行的进程
• 另请参阅

简介

使用 Microsoft Visual Studio Code 调试在 WebView2 控件中运行的脚本。

Visual Studio Code 具有用于浏览器调试的内置调试器。 请参阅 VS Code 中的浏览器调试。

创建launch.json文件

若要调试代码，项目必须具有 launch.json 文件。 launch.json文件是一个调试器配置文件，用于配置和自定义 Visual Studio Code 调试器。 配置调试程序 request 所需的属性之一是属性。 有两种 request 类型： launch 和 attach。

下面的代码演示了如何从 Visual Studio Code (启动应用，而不是将调试器附加到应用) 的正在运行的实例。 为此，必须以前已生成该应用。 如果你的项目没有launch.json文件，请在当前项目的子文件夹中.vscode创建一个新launch.json文件，并将以下代码粘贴到其中：

"name": "Hello debug world",
"type": "msedge",
"port": 9222, // The port value is optional, and the default value is 9222.
"request": "launch",
"runtimeExecutable": "C:/path/to/your/webview2/app.exe",
"env": {
   // The following variable is needed when the "runtimeExecutable" property is set.
   // The port number below must match the value of the "port" property above.
   "WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS": "--remote-debugging-port=9222"
   // Customize for your app location.
   "Path": "%path%;e:/path/to/your/app/location; "
},
"useWebView": true,
// The following two lines set up source path mapping, where "url" is the start page
// of your app, and "webRoot" is the top-level directory containing all your code files.
"url": "file:///${workspaceFolder}/path/to/your/toplevel/foo.html",
"webRoot": "${workspaceFolder}/path/to/your/assets"

使用注册表值

您可以将名为 with data --remote-debugging-port=9222 的新<myApp.exe>注册表值添加到注册表项下的注册表中Computer\HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments，以便调试器可以找到正确的端口，而不是设置WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS环境变量。 有关详细信息，请参阅 WebView2 浏览器标志。

传入的命令行 URL 参数

Visual Studio Code 源路径映射现在需要 URL，因此应用现在会在启动时收到命令url行参数。 如果需要，可以放心地忽略该 url 参数。

调试代码

1. 若要在源代码中设置断点，请单击一行代码，然后按 F9：

   

2. 在 “运行 ”选项卡上，从下拉菜单中选择启动配置。

3. 单击 Start Debugging，这是启动配置下拉列表旁边的绿色三角形：

   

4. 若要查看调试输出和错误，请打开 调试控制台：

   

目标 WebView2 调试

在某些 WebView2 应用中，可能会使用多个 WebView2 控件。 若要选择在这种情况下要调试的 WebView2 控件，可以使用目标 WebView2 调试。

打开 launch.json 并完成以下操作以使用目标 WebView2 调试。

1. 确认 useWebview 参数设置为 true。

2. 添加 urlFilter 参数。 当 WebView2 控件导航到 URL 时， urlFilter 参数值用于比较 URL 中显示的字符串。

"useWebview": "true",
"urlFilter": "*index.ts",

// Options for "urlFilter":
// Match any url that ends with "index.ts":
"urlFilter": "*index.ts",
// Match any url that contains "index" anywhere in the URL:
"urlFilter": "*index*",
// Explicitly match a file named "index.ts":
"urlFilter": "file://C:/path/to/my/index.ts",

调试应用时，可能需要从呈现过程的一开始逐步调试代码。 如果在网站上呈现网页，并且无权访问源代码，则可以使用该 ?=value 选项，因为网页会忽略无法识别的参数。

无法同时调试两个 WebView2 控件

在 URL 中找到第一个匹配项后，调试器将停止。 不能同时调试两个 WebView2 控件，因为 CDP 端口由所有 WebView2 控件共享，并使用单个端口号。

调试正在运行的进程

可能需要将调试器附加到正在运行的 WebView2 进程。 为此，请在 launch.json中更新 request 参数，将其值更改为 attach：

"name": "Hello debugging world",
"type": "msedge",
"port": 9222,
"request": "attach",
"runtimeExecutable": "C:/path/to/your/webview2/myApp.exe",
"env": {
   "Path": "%path%;e:/path/to/your/build/location; "
}

WebView2 控件必须打开 Chrome 开发人员协议 (CDP) 端口，才允许调试 WebView2 控件。 在启动调试器之前，必须构建代码以确保只有一个 WebView2 控件打开了 CDP 端口。

还需要在下添加一个新的 REGKEY <myApp.exe> = --remote-debugging-port=9222Computer\HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments，以便调试器可以找到正确的端口。 添加此注册表项：

1. 按 Windows 徽标键 ，然后搜索 注册表编辑器。 打开 注册表编辑器 应用，然后单击“ 是 ”以允许编辑。

2. 在左侧的文件夹树中，尝试展开 HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments。

3. 如果该路径的一部分不存在，请 \Edge\WebView2\AdditionalBrowserArguments 创建这三个嵌套子文件夹，如下所示：

   1. 要创建子文件夹，请执行以下 \Edge 操作： 在文件夹树中，右键单击 HKEY_CURRENT_USER\Software\Policies\Microsoft 文件夹，将鼠标悬停在“ 新建”上，然后选择“ 密钥”。 文件夹被添加为该 Microsoft 文件夹的子文件夹，最初名为 New Key #1。 右键单击 New Key #1 文件夹，然后选择“ 重命名”。 Enter Edge 新密钥的名称。

   2. 创建子 \WebView2 文件夹，如上一步所示。

   3. 创建子 \AdditionalBrowserArguments 文件夹，如上一步所示。

      树现已展开到 HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments。

4. 右键单击 AdditionalBrowserArguments 文件夹，将鼠标悬停在 “新建”上，然后选择“ 字符串值”。 在 “名称 ”列中，右键单击 New Value #1，选择“ 重命名”，然后输入应用可执行文件的文件名，例如 myApp.exe。

5. 在 “名称 ”列中，右键单击可执行文件名，如 myApp.exe，然后选择“ 修改”。 “ 编辑字符串 ”对话框将打开。

6. 在“值数据”文本框中，输入：--remote-debugging-port=9222

   

7. 单击“确定”按钮，然后验证注册表项是否与以下 (匹配与“名称”列) 中的文件名.exe匹配：

   

使用环境变量

可以将环境变量--remote-debugging-port=9222设置为 WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS ，而不是添加上述注册表项。 请确保应用程序在设置环境变量后启动，并确保应用程序继承环境变量。 有关详细信息，请参阅 WebView2 浏览器标志。

调试跟踪选项

要启用调试跟踪，请将参数launch.json添加到 trace ，如下所示：

1. 添加 trace 参数：

"name": "Hello debugging world",
"type": "msedge",
"port": 9222,
"request": "attach",
"runtimeExecutable": "C:/path/to/your/webview2/app.exe",
"env": {
"Path": "%path%;e:/path/to/your/build/location; "
},
"useWebView": true
,"trace": true  // Turn on debug tracing, and save the output to a log file.

将调试输出保存到日志文件：

,"trace": "verbose"  // Turn on verbose tracing in the Debug Output pane.

“调试控制台”窗格中的 Visual Studio Code 输出，其中启用了详细跟踪：

调试 Office 加载项

如果要调试 Office 加载项，请在单独的 Visual Studio Code 实例中打开加载项源代码。 在 WebView2 应用中打开 launch.json 。 将以下代码 launch.json添加到 中，以将调试器附加到 Office 加载项：

,"debugServer": 4711

调试 WebView2 WinUI 2 (UWP) 应用

1. 安装过去 106.0.1370.34的 WebView2 运行时版本。

2. 按 Windows 徽标键 ，然后搜索 注册表编辑器，打开注册表编辑器。 打开 注册表编辑器 应用程序，然后选择“ 是 ”以允许编辑。

3. 将注册表项HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments--remote-debugging-pipe设置为 。 为此，请按照上面“ 调试正在运行的进程 ”部分中所述的步骤操作。

4. 验证注册表项是否已在编辑器中设置，并与以下内容匹配：

   

5. 向文件 launch.json 添加新配置。 打开 launch.json 并添加以下代码：

   "name": "Attach to UWP App",
   "useWebView":{
      "pipeName":"JSDebugPipe"
   }
   "request": "attach",
   "type": "msedge",
   "webRoot":"${workspaceFolder}"
   

6. 启动应用。

7. 单击“ 开始调试 ”按钮以附加到进程并开始调试。

   

源映射与 WebResourceRequested 事件或虚拟主机名映射

需要源映射来调试已编译内容的源代码，包括：

• 转编的 JavaScript，例如 TypeScript 或缩小的 JavaScript。
• 已编译的 CSS，例如 SASS 或 SCSS。

WebView2 不会加载由使用任一方法加载的内容引用的源映射：

• 该 WebResourceRequested 事件。 请参阅：

  • 通过在 WebView2 应用中使用本地内容中处理WebResourceRequested事件来加载本地内容。
  • 源映射与WebResourceRequested“在 WebView2 应用中使用本地内容”中的事件。

• 虚拟主机名映射。 请参阅：

  • 在“在 WebView2 应用中使用本地内容”中使用虚拟主机名映射加载本地内容。
  • 在 WebView2 应用中使用本地内容中具有虚拟主机名映射的源映射。

调试程序疑难解答

使用调试器时，可能会遇到这些情况。

不停在断点

如果调试器未在断点处停止，并且你有调试输出：

若要解决此问题，请确认具有断点的文件与 WebView2 控件使用的文件相同。 调试器不执行源路径映射。

无法附加到正在运行的进程

如果无法附加到正在运行的进程，并收到超时错误：

若要解决此问题，请确认 WebView2 控件已打开 CDP 端口。 请确保 additionalBrowserArguments 注册表中的值正确，或者选项正确。 请参阅 dotnet 的 additionalBrowserArguments 和 Win32 的 additionalBrowserArguments。

另请参阅

• WebView2 入门
• WebView2Samples 存储库 - WebView2 功能的综合示例。
• WebView2 API 参考