使用 Visual Studio Code 除錯 WebView2 應用程式

使用 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"

使用登錄值

你可以不用設定WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS環境變數，而是在登錄檔鍵Computer\HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments下新增一個用資料--remote-debugging-port=9222命名<myApp.exe>的新登錄檔值，讓除錯器能找到正確的埠。 欲了解更多資訊，請參閱 WewbView2 瀏覽器旗標。

命令列 URL 參數傳遞

Visual Studio Code 的原始碼路徑映射現在需要一個 URL，因此你的應用程式在啟動時會url收到一個命令列參數。 如果需要，你可以放心忽略這個 url 參數。

除錯你的程式碼

1. 要設定原始碼中的中斷點，請點擊一行程式碼，然後按 F9：

   

2. 在 執行 標籤中，從下拉選單選擇啟動設定。

3. 點擊啟動設定下拉選單旁的綠色三角形，點擊 開始除錯：

   

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 控制項必須 (CDP) 埠開啟 Chrome 開發者協定，才能進行除錯 WebView2 控制項。 你的程式碼必須先建立以確保只有一個 WebView2 控制項開啟 CDP 埠，然後才啟動除錯器。

你還需要在 下Computer\HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments新增一個新的 REGKEY<myApp.exe> = --remote-debugging-port=9222，讓除錯器能找到正確的埠。 補充這個登錄檔鍵：

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 然後選擇 重新命名。 輸入 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 (相符：

   

使用環境變數

你可以不新增上述登錄檔鍵，而是將環境變數設 WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS 為 --remote-debugging-port=9222。 確保你的應用程式是在環境變數設定後才啟動，並且你的應用程式繼承了環境變數。 欲了解更多資訊，請參閱 WewbView2 瀏覽器旗標。

除錯追蹤選項

要啟用除錯追蹤，請在 中加入 trace 參數 launch.json ，如下：

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. 安裝一個 WebView2 執行時版本，超過 106.0.1370.34。

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事件來載入本地內容。
  • 在 WebView2 應用程式中使用本地內容時，包含事件的WebResourceRequested原始地圖。

• 虛擬主機名稱映射。 請參閱：

  • 在 WebView2 應用程式中使用虛擬主機名稱映射來載入本地內容。
  • 在 WebView2 應用程式中使用本地內容時，提供帶有虛擬主機名稱映射的原始碼地圖。

排除除錯器問題

使用除錯器時你可能會遇到這些情況。

它不會在斷點就結束

如果除錯器沒有在斷點停止，且你有除錯輸出：

要解決這個問題，請確認帶有斷點的檔案是否與 WebView2 控制項使用的檔案相同。 除錯器不會執行來源路徑映射。

無法連接到正在執行的程序

如果你無法連接到正在執行的程序，且出現逾時錯誤：

要解決這個問題，請確認 WebView2 控制項是否開啟了 CDP 埠。 確保你 additionalBrowserArguments 登記冊上的價值正確，或選項是否正確。 請參見 AdditionalBrowserArguments for dotnet 及 additionalBrowserArguments for Win32。

另請參閱

• 開始使用 WebView2
• WebView2Samples 儲存庫 ——WebView2 功能的完整範例。
• WebView2 API 參考