Web 图形与 3D / 系统课时

检查 WebGPU 支持和安全上下文

检查 WebGPU 支持和安全上下文

WebGPU 无法启用时,原因可能是页面不满足安全上下文要求、浏览器没有暴露 API,或者设备无法提供 GPU 适配器。本课通过一段可执行的检测代码逐层定位问题,并给出本地开发和正式部署时的处理方法。

学习目标

  • 判断当前页面是否满足 WebGPU 的安全上下文要求。
  • 使用 navigator.gpu、requestAdapter() 和 requestDevice() 验证实际可用性。
  • 根据检测结果区分浏览器限制、GPU 环境问题和设备初始化失败。

识别安全上下文要求

WebGPU 属于受安全上下文限制的浏览器 API。即使计算机安装了支持 WebGPU 的浏览器和显卡驱动,页面来源不满足安全要求时,navigator.gpu 仍可能不可用。

浏览器通过只读属性 window.isSecureContext 判断当前页面是否处于安全上下文。常见访问地址的判断如下:

页面地址 通常是否属于安全上下文 说明
https://example.com 是 正常建立可信 HTTPS 连接
http://localhost:5173 是 本机开发地址属于可信来源
http://127.0.0.1:5173 是 本机回环地址属于可信来源
http://192.168.1.10:5173 否 普通局域网 HTTP 地址不自动获得豁免
http://example.com 否 普通远程 HTTP 页面

表中的 5173 只是开发服务器端口示例,实际端口以项目启动信息为准。file:// 页面通常也可能被认定为安全上下文,但模块加载和文件访问还会受到其他限制,建议使用本地 HTTP 开发服务器。

还要检查页面的嵌入关系:即使某个 iframe 自身使用 HTTPS,只要它的祖先页面不属于安全上下文,该 iframe 也不能仅凭自身的 HTTPS 获得安全上下文资格。

执行 WebGPU 能力检测

仅检查 navigator.gpu 是否存在还不够。浏览器可能已经暴露 API,但由于显卡驱动、GPU 加速策略或运行环境限制,无法提供适配器或创建设备。

完整的能力检测应依次完成四项检查:安全上下文、API 入口、GPU 适配器和 GPU 设备。前一步失败时立即停止,避免继续调用不存在的对象。

在 Chrome、Edge 或 Firefox 中打开需要检查的页面,按 F12 打开开发者工具,切换到 Console(控制台),粘贴运行下面的完整 JavaScript:

js
(async function checkWebGPU() {
  console.log(`安全上下文:${window.isSecureContext ? '是' : '否'}`);

  // 不满足安全上下文要求时,不继续访问受限制的 API。
  if (!window.isSecureContext) {
    console.warn('结论:当前页面不是安全上下文');
    return;
  }

  if (!navigator.gpu) {
    console.warn('结论:浏览器未暴露 WebGPU API');
    return;
  }
  console.log('WebGPU API:已暴露');

  try {
    // API 存在不代表当前环境一定能分配 GPU 适配器。
    const adapter = await navigator.gpu.requestAdapter();
    if (!adapter) {
      console.warn('结论:未获取 GPU 适配器');
      return;
    }
    console.log('GPU 适配器:已获取');

    const device = await adapter.requestDevice();
    console.log('GPU 设备:已创建');

    // 本次仅检测能力,不保留测试设备占用资源。
    device.destroy();
    console.log('结论:WebGPU 初始化检查通过(测试设备已释放)');
  } catch (error) {
    console.error('结论:WebGPU 初始化失败', error);
  }
})();

预期输出: 在支持 WebGPU 且能够成功创建设备的环境中,控制台会依次显示:

text
安全上下文:是
WebGPU API:已暴露
GPU 适配器:已获取
GPU 设备:已创建
结论:WebGPU 初始化检查通过(测试设备已释放)

开发者工具还可能显示异步函数的 Promise 回显,不属于上述状态日志。如果某一步失败,程序会输出对应的结论并提前结束;设备申请抛出异常时,还会显示浏览器提供的错误详情。

这里的 requestAdapter() 返回一个 Promise,成功时得到 GPUAdapter,没有适合当前请求的适配器时可能返回 null。adapter.requestDevice() 则负责申请真正用于提交 GPU 工作的 GPUDevice。

通过检测仅表示当前页面能够初始化一个 WebGPU 设备,并不等于已经成功编译 WGSL、创建渲染管线或执行计算任务。

根据检测结果定位问题

四级检测把原本模糊的“WebGPU 不支持”拆分为不同的失败位置。下图展示每一级的通过条件及失败后的排查方向。

WebGPU 从安全上下文到 GPU 设备申请的分层检测流程

检测结果 可能原因 优先处理方式
安全上下文:否 使用普通 HTTP 或受到不安全祖先页面影响 改用 HTTPS、本机 localhost,并检查 iframe 所在页面
未暴露 WebGPU API 浏览器版本、平台支持或策略限制 更新受支持的浏览器,核对平台兼容性与浏览器策略
未获取 GPU 适配器 GPU 不可用、驱动问题、硬件加速受限 检查显卡驱动、GPU 加速和虚拟机或远程桌面环境
WebGPU 初始化失败 设备申请失败或浏览器运行环境异常 查看异常名称与详情,排查设备及资源限制

在 Chromium 系浏览器中,还可以通过浏览器提供的 GPU 诊断页面辅助定位。例如 Chrome 的地址栏可输入 chrome://gpu,查看 Graphics Feature Status 中与 WebGPU 相关的状态信息。

该诊断页面显示的是浏览器图形功能状态,不能代替页面中的 requestAdapter() 和 requestDevice() 实际检测。

浏览器对 WebGPU 的支持会随版本、操作系统和图形驱动变化,不应该仅凭用户使用 Chrome、Safari 或 Firefox 就认定功能可用。需要确认当前兼容性时,可查阅 MDN 的 navigator.gpu 文档及其中的浏览器兼容性表。

验收本地开发与正式部署

建议分别在本机开发地址和实际部署地址运行同一段检测代码,以排除环境差异。

  1. 本地开发: 启动项目的开发服务器,通过 http://localhost:实际端口 访问页面。不要把普通局域网 HTTP 地址当作本机回环地址。
  2. 浏览器检查: 在目标浏览器运行检测代码,确认安全上下文、API、适配器和设备四项依次通过。对于失败的设备申请,保留原始异常信息。
  3. 线上部署: 使用 HTTPS 访问正式域名,重新执行检测。如果页面嵌入其他网站,还要检查顶层页面及其他祖先页面是否满足安全上下文要求。
  4. 应用降级: 页面启动时先检测 WebGPU,检测失败则显示明确原因,并根据实际功能选择 WebGL2 降级方案、静态预览或不支持提示,避免留下空白画布。

验收时应分别记录访问地址、浏览器版本、操作系统、检测阶段和错误信息。这样即使两台设备使用相同浏览器,也能准确区分安全上下文限制、API 缺失和 GPU 初始化失败。

只有通过四级检查后,应用才适合继续创建 WebGPU 渲染或计算管线。后续使用特定纹理格式、工作组尺寸或可选 GPU 功能时,还需要进一步检查适配器的 features 和 limits,不能把基础初始化成功当成所有高级能力都已得到支持。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

检查 WebGPU 支持和安全上下文

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通