WebGPU：问题排查提示和修复

François Beaufort
François Beaufort
GitHub

本文档介绍了 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 和 Android 上的 Chrome 121 或更高版本上使用 Chrome 113 或更高版本。请前往 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. 当用户关闭“使用图形加速（如果可用）”后，系统会停用 WebGPU在 chrome://settings/system 中。请检查此设置是否已关闭并重新开启

  2. 此平台尚不支持 WebGPU。您可以启用 chrome://flags/#enable-unsafe-webgpu 标志并重启 Chrome。如需获得 Linux 实验性支持，您还需要启用 chrome://flags/#enable-vulkan 标志。如需了解详情，请参阅 Headless Chrome 中的 WebGPU 支持。

  3. GPU 硬件已被明确列入屏蔽名单。如果您看到“已通过屏蔽名单或命令行停用 WebGPU”的消息，在 chrome://gpu 中，您可以通过启用 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 适配器，考虑到耗电量（例如省电），笔记本电脑的 GPU 适配器通常是集成显卡。这意味着，powerPreference 选项在调用 requestAdapter() 时不会产生任何影响。