浏览器跑大模型：你的浏览器到底支不支持 WebGPU？

一个“假支持”的真实事故

使用者痛点：页面渲染正常、按钮可点，却在点击 “Load model” 时收到 “WebGPU is not supported” 的错误。其实，

你已经在最开头用了下面的检测：

const IS_WEBGPU_AILABLE =!，怎么说呢，navigator.gpu;

这个布尔值为 true于是 UI 正常渲染。但真正使用时却提示不支持。因为该检测只回答了 “API 在不在”，没有回答 “硬件能不能”。

主要陷阱：navigator.gpu 存在 ≠ 机器真的能跑 WebGPU。Chrome 可能暴露了接口，但底层驱动旧、虚拟显卡不兼容、或被列入黑名单——导致 requestAdapter 返回 null从而出现“假支持”。按理说，

要避免这种情况。必须进行 **两层检测**：第一层特性检测决定 UI 骨架，第二层能力检测确认硬件真的可用。

一、全貌概览：两层检测分别在哪里？

const IS_WEBGPU_AILABLE =!，navigator.gpu;

const adapter = await navigator.gpu.requestAdapter;

使用者痛点回顾：只做第一层会怎样？

• #1 假支持崩溃：页面渲染正常。点击加载后 Worker 调用 requestAdapter` 返回 null，随后报错。
• #2 错误信息晦涩：User sees a generic “Loading model...” n an unexpected crash without clear原因。
• #3 资源浪费：
• #4 开发者调试成本高：

• #1 TypeError：
• #2 UI 无法提前降级：
• #3 开发者需要额外的 try/catch 包装每一次 API 调用。

二、第一层：!，navigator.gpu —— 同步特性检测

说到代码示例。

// App.tsx —— 模块顶层，页面加载就执行
const IS_WEBGPU_AILABLE =!，navigator.gpu;

• *判断* 浏览器是否实现了 WebGPU 接口；返回 true 时表示入口对象存在。
• *决定* UI 骨架——通过三元运算符直接切换整棵组件树，而不是渲染后弹窗提示。按理说，
• *同步* 完成。因为它必须在第一次渲染前决定哪棵树要被挂载。若改为异步，React 首帧仍会尝试渲染完整 UI。从而可能因后续访问

return (
IS_WEBGPU_AILABLE?(

{/* 正常聊天 UI */}

) : (

WebGPU is not supported
by this browser :(

)
);

⚠️ 必须同步的原因

If you perform check after first render,initial render will still try to access

三、第二层： —— 异步能力检测

触发地点的观点是。

// 创建 Worker 并发送检查指令
useEffect => {
if {
worker.current = new Worker,{
从type来看，"module",});worker.current.postMessage;}
},)，

Worker 中的实际检查逻辑：

async function check {
try {
const adapter = await navigator.gpu.requestAdapter;if {
throw new Error");}
// 可选
点：探测 fp16 支持等
// const fp16_supported = adapter.features.has;
} catch {
self.postMessage });}
}
self.onmessage = async => {
if await check;}，话说回来，

• *异步* 调用底层驱动。让显卡/驱动自行决定是否能提供适配器；若不行返回 null**.
• *显式检查 null* —— `requestAdapter` 不会抛异常，它返回 `null` 表示不可用。若忽略此检查，后续 `adapter.requestDevice` 会直接报 `Cannot read property 'requestDevice' of null`。
• *错误回传* —— 使用 `postMessage` 把错误信息传回主线程。由 UI 显示红色提示，实现“能力检测失败即刻反馈”。
• * 空间* —— 注释中的 `adapter.features.has` 示意第三层探测，可进一步判断半精度浮点等高级特性。

⚡️ 为什么把这一步放进 Worker 而不是主线程？

• 避免卡顿初始化 GPU 上下文可能耗时且涉及显卡唤醒，在主线程执行会阻塞页面交互和渲染。
• 职责分离后续所有推理计算也都在 Worker 中完成。把“检测 → 加载 → 推理”串成一条完整的工作流链路，使主线程只负责 UI 与消息转发。
• 资源隔离即便适配器获取失败，也不会占用主线程资源；Worker 可以直接 terminate 或保持空闲状态。
\

四、两层对比图示

✅ 两层都做，你得到什么？

• 第一层 把完全没有 API 的浏览器挡在门外——无需创建任何 Worker，也不会出现运行时 TypeError。
• 第二层 在进入内部流程前 体检硬件。如果适配器缺失立即给出明确错误，而不是等到模型下载一半才崩溃。
• 整体体验 —— 使用者要么看到完整功能。要么立刻得到清晰的“不支持”说明，两者之间没有模糊地带。\

五、TypeScript 类型治理：让 navigator.gpu 不再报红

If you write in TS。you’ll see:

Property 'gpu' does not exist on type 'Navigator'

The project solves it by adding official WebGPU type definitions:

{
"compilerOptions": {
至于"lib"，"types":
//…其他配置
}
}

• @webgpu/types 提供了 NavigatorGPUAdapterGPUSupportedFeatures 等完整声明。
• 为什么单独安装？ 因为 WebGPU 尚未正式进入 ECMAScript 标准库，TS 官方库暂未收录对应声明。独立包可以随规范迭代快速更新。
• 注意坑: 必须把包写入 tsconfig.json 的 types 数组里否则 TS 不会自动加载，即使已 npm i @webgpu/types。该数组是白名单，一旦出现，就只加载列出的声明文件。不再扫描全局 node_modules/@types。
\

🚀 Vite 配置无需额外修改

`vite.config.ts` 保持默认即可；WebGPU 检测完全是运行时行为，与建立阶段无关。不过，只要确保 TS 能识别类型即可顺利编译并得到 IDE 自动补全。

六、Worker 检测 vs 主线程检测：何时该放哪儿？

The rule of thumb:

• If you only need a boolean to decide what to render。do it synchronously on main thread.
• If check requires heavy async work or will be followed by subsequent GPU commands,push it into a Worker.
\

七、检测的本质是“对使用者诚实”

The two‑layer design can be boiled down to two simple questions:

#1 第一层 ) :"Does this browser expose WebGPU entry point?" – answers API existence. #2 第二层 ) :"Can I actually get a GPU adapter on this machine?" – answers hardware capability. \

Each layer only answers its own question and never assumes or. This disciplined separation prevents:

• Mistaking “API exists” for “it works”.​​​​​​​​​​​

The same philosophy applies to any runtime‑dependent feature . Always ask both “Is API re?不过，” and “Can I really use it?”.