WebGPU:问题排查提示和修复

François Beaufort
François Beaufort

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

以下示例展示了当 gpunavigator 中不可用时您可能会收到的 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://localhosthttp://127.0.0.1 上本地提供代码:npx http-serverpython3 -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() 时不会产生任何影响。