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. 在 ChromeOS、macOS 和 Windows 上，WebGPU 需要 Chrome 113 或更高版本；在 Android 上，则需要 Chrome 121 或更高版本。请访问 chrome://version 检查您的版本，并根据需要进行更新。

  2. 只有安全情境才能访问 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 将本地 Web 服务器公开到互联网。

GPU 适配器为 null

以下是调用 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 适配器屏蔽名单。

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

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

  6. GPU 进程多次崩溃。您可以重新加载网页或重启 Chrome。如需了解详情，请参阅 WebGPU 设备丢失最佳实践。

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 选项不会产生任何影响。