WebGPU：问题排查提示和修复

François Beaufort
François Beaufort
GitHub

本文档介绍了 WebGPU 在 Chrome 浏览器中可能无法运行或无法按预期运行的原因，并尽可能提供了解决相关问题的清晰步骤。

以下示例展示了当 navigator 中无法使用 gpu 时您可能会收到的 JavaScript 错误：

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

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

而这可能是由于以下某个原因所致。请按如下顺序查看这些建议：

  1. WebGPU 要求在 ChromeOS、macOS、Windows 和 Chrome 121 或更高版本的 Android 设备上使用 Chrome 113 或更高版本。请访问 chrome://version 查看您的版本，并根据需要进行更新。

  2. 目前无法通过 Service Worker 或 Shared Worker 访问 WebGPU。如果使用 Service Worker 或 Shared Worker，请将您的 WebGPU 代码移至专用 worker 或全局窗口上下文。

  3. 只有安全上下文才能访问 WebGPU。如果您通过不安全的协议（例如 http:、file:）提供代码，请使用安全的 https: 协议，或者在开发 Web 应用时通过以下某种方式解决此问题：

    • 您可使用以下任一命令，在 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 适配器为 null

以下是当您通过调用 requestAdapter() 获取的适配器为 null 时可能会收到的 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 标志。如需了解详情，请参阅 Headless Chrome 中的 WebGPU 支持。

  3. GPU 硬件已被明确列入屏蔽名单。如果您在 chrome://gpu 中看到“WebGPU 已通过屏蔽名单或命令行停用”，则可以通过启用 chrome://flags/#enable-unsafe-webgpu 标志并重启 Chrome 来停用 WebGPU 适配器屏蔽名单。

  4. 没有与 requestAdapter() 中传递的选项匹配的 GPU 适配器。尝试使用不同的选项调用 requestAdapter()。

  5. WebGPU 需要 GPU（硬件模拟或软件模拟）。您可以访问 chrome://gpu，检查 Chrome 是否检测到 GPU。

WebGPU 的运行速度比 WebGL 慢

  1. 打开 chrome://gpu，并确保您可以阅读“WebGPU: Hardware accelerated”。如果您看到“WebGPU：仅限软件，硬件加速不可用”，则可能需要更新 GPU 驱动程序。

  2. 将 WebGL 概念直接转换为 WebGPU 可能无法充分利用 WebGPU 的独特优化。请参阅从 WebGL 到 WebGPU，了解它们的一些差异。

Windows 特有的限制

在 Windows 设备上使用 WebGPU 时，请注意以下限制：

  • Chrome 不支持同时使用多个 GPU 适配器。请参阅问题 chromium:329211593。

  • Chrome 始终使用已分配给其他 Chrome 工作负载的同一 GPU 适配器，出于功耗方面的考虑（即省电），对于笔记本电脑，该适配器通常是集成显卡。这意味着在调用 requestAdapter() 时，powerPreference 选项没有任何影响。