WebGPU：疑難排解提示和修正

François Beaufort
François Beaufort
GitHub

發布日期：2024 年 2 月 7 日，上次更新時間：2025 年 10 月 17 日

本文說明 WebGPU 可能無法運作或無法在 Chrome 瀏覽器中正常運作的原因，並提供清楚的步驟，盡可能解決問題。

以下範例顯示 navigator 中沒有 gpu 時，您可能會收到的 JavaScript 錯誤：

const adapter = await navigator.gpu.requestAdapter();

cancel Uncaught TypeError: Cannot read properties of undefined (reading 'requestAdapter')

可能原因如下：請依下列順序查看：

  1. 如要在 ChromeOS、macOS 和 Windows 上使用 WebGPU，必須安裝 Chrome 113 以上版本；如要在 Android 上使用，則必須安裝 Chrome 121 以上版本。前往 chrome://version 查看版本，並視需要更新。

  2. WebGPU 只能在安全環境中使用。如果您透過不安全的通訊協定 (例如 http:、file:) 提供程式碼，請使用安全的 https: 通訊協定，或在開發網頁應用程式時，透過下列其中一種方式解決這個問題：

    • 使用下列任一指令，在本機的 http://localhost 或 http://127.0.0.1 上提供程式碼：npx http-server 或 python3 -m http.server。

    • 將來源新增至 chrome://flags/#unsafely-treat-insecure-origin-as-secure 的「視為安全的不安全來源」清單，然後重新啟動 Chrome。

    • 安裝 Node.js 並執行 npx servez --ssl，透過 https 和偽造憑證提供資料夾。Chrome 仍會顯示警告，但您可以點選「進階」和「繼續前往...」略過警告。

    • 使用 ngrok 將本機網路伺服器公開至網際網路。

GPU 介面卡為空值

以下是您從呼叫 requestAdapter() 取得的介面卡為空值時，可能會收到的 JavaScript 錯誤範例：

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();

cancel Uncaught TypeError: Cannot read properties of undefined (reading requestDevice)

發生這種情況的原因如下。請依下列順序查看：

  1. 如果使用者在 chrome://settings/system 中關閉「使用圖形加速功能 (如果可用)」，系統就會停用 WebGPU。確認這項設定是否已關閉，並重新開啟

  2. 這個平台目前不支援 WebGPU。啟用 chrome://flags/#enable-unsafe-webgpu 旗標並重新啟動 Chrome。如要使用 Linux 實驗功能，您也需要啟用 chrome://flags/#enable-vulkan 標記。如要瞭解詳情，請參閱「無頭 Chrome 中的 WebGPU 支援」。

  3. GPU 硬體已加入封鎖清單。如果 chrome://gpu 中顯示「WebGPU 已透過封鎖清單或指令列停用」，您可以啟用 chrome://flags/#enable-unsafe-webgpu 旗標並重新啟動 Chrome，停用 WebGPU 轉接器封鎖清單。您也可以啟用 chrome://flags/#ignore-gpu-blocklist 標記並重新啟動 Chrome，覆寫內建的軟體算繪清單。

  4. requestAdapter() 中傳遞的選項沒有相符的 GPU 轉接器。嘗試使用其他選項撥打 requestAdapter()。

  5. WebGPU 需要 GPU (硬體或軟體模擬)。如要確認 Chrome 是否偵測到 GPU，請前往 chrome://gpu。

  6. GPU 程序多次當機。你可以重新載入頁面或重新啟動 Chrome。如要瞭解詳情，請參閱 WebGPU 裝置遺失最佳做法。

WebGPU 比 WebGL 慢

  1. 開啟 chrome://gpu，確認你可以讀取「WebGPU: Hardware accelerated」(WebGPU：硬體加速)。如果看到「WebGPU：僅限軟體，無法使用硬體加速功能」，可能需要更新 GPU 驅動程式。

  2. 直接將 WebGL 概念轉換為 WebGPU，可能無法充分運用 WebGPU 的獨特最佳化功能。如要瞭解兩者之間的差異，請參閱「從 WebGL 到 WebGPU」。

Windows 特有的限制

在 Windows 裝置上使用 WebGPU 時，請注意下列限制：

  • Chrome 不支援同時使用多個 GPU 配接器。請參閱問題 chromium:329211593。

  • Chrome 一律會使用分配給其他 Chrome 工作負載的相同 GPU 配接器，由於筆電的耗電量較高 (即省電)，因此通常是整合式顯示卡。也就是說，呼叫 requestAdapter() 時，powerPreference 選項不會有任何影響。如要強制使用高效能 GPU (如有)，請啟用 chrome://flags/#force-high-performance-gpu 旗標並重新啟動 Chrome。