WebGPU：问题排查提示和修复

François Beaufort
François Beaufort
GitHub

发布时间：2024 年 2 月 7 日；上次更新时间：2025 年 10 月 17 日

本文档介绍了 WebGPU 在 Chrome 浏览器中可能无法运行或无法按预期运行的原因，并提供了清晰的步骤来解决这些问题（如果可能）。

以下示例展示了当 gpu 在 navigator 中不可用时，您可能会遇到的 JavaScript 错误：

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

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

这可能是由于以下某个原因所致。请按以下特定顺序查看这些内容：

  1. WebGPU 需要 ChromeOS、macOS、Windows 上的 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() 获取的适配器为 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 标志。如需了解详情，请参阅无头 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：仅限软件，硬件加速不可用”，则可能需要更新 GPU 驱动程序。

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

Windows 特有的限制

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

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

  • Chrome 始终使用已为其他 Chrome 工作负载分配的同一 GPU 适配器，对于笔记本电脑而言，由于功耗方面的原因（即省电），该适配器通常是集成显卡。这意味着，在调用 requestAdapter() 时，powerPreference 选项没有任何影响。您可以启用 chrome://flags/#force-high-performance-gpu 标志并重启 Chrome，以强制使用高性能 GPU（如果可用）。