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:
(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 且能够成功创建设备的环境中,控制台会依次显示:
安全上下文:是
WebGPU API:已暴露
GPU 适配器:已获取
GPU 设备:已创建
结论:WebGPU 初始化检查通过(测试设备已释放)开发者工具还可能显示异步函数的 Promise 回显,不属于上述状态日志。如果某一步失败,程序会输出对应的结论并提前结束;设备申请抛出异常时,还会显示浏览器提供的错误详情。
这里的 requestAdapter() 返回一个 Promise,成功时得到 GPUAdapter,没有适合当前请求的适配器时可能返回 null。adapter.requestDevice() 则负责申请真正用于提交 GPU 工作的 GPUDevice。
通过检测仅表示当前页面能够初始化一个 WebGPU 设备,并不等于已经成功编译 WGSL、创建渲染管线或执行计算任务。
根据检测结果定位问题
四级检测把原本模糊的“WebGPU 不支持”拆分为不同的失败位置。下图展示每一级的通过条件及失败后的排查方向。

| 检测结果 | 可能原因 | 优先处理方式 |
|---|---|---|
| 安全上下文:否 | 使用普通 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 文档及其中的浏览器兼容性表。
验收本地开发与正式部署
建议分别在本机开发地址和实际部署地址运行同一段检测代码,以排除环境差异。
- 本地开发: 启动项目的开发服务器,通过
http://localhost:实际端口访问页面。不要把普通局域网 HTTP 地址当作本机回环地址。 - 浏览器检查: 在目标浏览器运行检测代码,确认安全上下文、API、适配器和设备四项依次通过。对于失败的设备申请,保留原始异常信息。
- 线上部署: 使用 HTTPS 访问正式域名,重新执行检测。如果页面嵌入其他网站,还要检查顶层页面及其他祖先页面是否满足安全上下文要求。
- 应用降级: 页面启动时先检测 WebGPU,检测失败则显示明确原因,并根据实际功能选择 WebGL2 降级方案、静态预览或不支持提示,避免留下空白画布。
验收时应分别记录访问地址、浏览器版本、操作系统、检测阶段和错误信息。这样即使两台设备使用相同浏览器,也能准确区分安全上下文限制、API 缺失和 GPU 初始化失败。
只有通过四级检查后,应用才适合继续创建 WebGPU 渲染或计算管线。后续使用特定纹理格式、工作组尺寸或可选 GPU 功能时,还需要进一步检查适配器的 features 和 limits,不能把基础初始化成功当成所有高级能力都已得到支持。