用 React 搭一个 WebGPU 模型加载页：从状态驱动到可复用进度条

在第一次做浏览器端 AI 页面时往往会把注意力全部放在“模型有多大、WebGPU 有多快”上。只是真正开始写界面后却会先遇到一组更基础的问题：

• 如何判断浏览器能否使用 WebGPU？
• 点击按钮后如何让页面从“等待”切换到“加载中”？
• 多个模型文件的进度怎样渲染？
• 为什么修改普通变量不会更新页面？

下面的示例不接入真正的模型推理库，而是完成一个可以独立运行的加载界面原型。它包含 WebGPU 能力检测、React 状态管理、点击事件、条件渲染、列表渲染和组件拆分。理解这条数据流以后再接入 Transformers.js 或 ONNX Runtime Web，就不会把网络下载、推理引擎和界面状态混在一起。

先搭好可以运行的项目

使用 Vite 创建 React 项目：

npm create vite@latest webgpu-demo -- --template reactcd
cd webgpu-demo
npm install
npm install tailwindcss @tailwindcss/vite
npx tailwindcss init -p

这里选择的是 JavaScript 模板，所以组件文件使用 .jsx。如果你更习惯 TypeScript，则改为 react-ts 模板并使用 .tsx。

package.json 示例脚本：

{
"scripts": {
说到"dev"，"vite","build": "vite build"。"preview": "vite preview"
}
}

vite.config.js 注册插件：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
plugins:,})

src/index.css 引入 Tailwind：

@import 'tailwindcss/base';@import 'tailwindcss/components';@import 'tailwindcss/utilities';话说回来，

WebGPU 检测到底检测了什么？

WebGPU 是浏览器提供的图形与通用计算接口。其实，要跑模型，需要先确认浏览器是否暴露了 GPU 接口。

• 最小检测代码：

const isWebGPUAvailable = Boolean

• 如果 navigator.gpu 存在说明浏览器至少支持进入 WebGPU 的入口。注意，这并不等于能够成功创建设备；后续还需要 requestAdapter 与 requestDevice。话说回来，
• WebGPU 通常要求安全上下文：localhost 或 HTTPS。 否则即使支持也无法拿到 navigator.gpu。
• 即便属性存在适配器申请或显存分配仍可能失败。实际使用需要捕获错误并展示给使用者。

用状态描述页面而不是手动修改 DOM

加载页至少需要保存三类会变化的数据：当前阶段、错误信息和文件进度。React 用 useState 保存这些数据：

const = useState // idle / loading / ready / error
const = useState
const = useState()

• "idle" 表示未开始；"loading" 表示正在下载；"ready" 表示全部完成；"error" 可作为 status 的一员来统一处理错误。
• "percentage" 用百分数或 null；按理说，null 表示尚未收到任何进度。

点击按钮时只需更新状态即可，React 会自动重新渲染页面：

加载模型
function handleLoad {
setError
setStatus
}

把进度条拆成可复用组件

Create a reusable Progress component in src/components/Progress.jsx:

function formatBytes {
if || bytes <=0) return '<1B'
  const units = 
  const unitIndex = Math.min/Math.log), units.length-1)
  const value = bytes/Math.pow
  return `${value.toFixed} ${units}`
}
export default function Progress {
   const safePercentage=Math.min)
   return (
     


{name}
{safePercentage}%






{formatBytes} / {formatBytes}


)
}

• The component receives props via destructuring with defaults.
• The width of inner div is controlled by inline style using template string.
• This component can be reused for any number of files without duplicating markup.

说到完整实现。让数据流真正连起来

import {useEffect,useState} from 'react'
import Progress from './components/Progress'
const initialFiles=
export default function App{
const =useState
const =useState
const =useState
const isWebGPUAvailable=Boolean
// 模拟下载逻辑
useEffect=>{
if return
const timer=setInterval=>{
setProgressItems(items=>items.map(i=>{
const next=Math.min+5)
return {...i,percentage:next,loaded:i.total*next/100}
}))
},300)
return=>clearInterval
},)
// 检查是否全部完成
useEffect=>{
if){
setStatus
}
},)
function handleLoad{
setError
setProgressItems))
setStatus
}
if{
return (


当前环境无法使用 WebGPU，请使用最新版浏览器，并确保页面通过 HTTPS 或 localhost 打开。
)
}
return (

{error && }

{status==='loading'?'加载中，': status==='ready'?'重新加载':'加载模型'}

{status!=='idle' && (

{status==='ready'?'模型文件已准备好':'正在准备模型文件'} 
{progressItems.map(item=>(
{)
)}

}
)
}
}

程序从打开页面到加载完成经历了什么?

1. The browser loads index.html → Vite bundles entry → React renders App into #root.
first runs with initial states.
2. Status check for navigator.gpu decides wher to show support banner.
3. If supported and status is idle it shows intro and button.
4. User clicks button → handleLoad clears error and sets status to loading.
5. Status update causes a re‑render – button becomes disabled and progress section appears.
6. The progress list maps each file to a Progress component passing props by spread operator.
7. A useEffect creates a timer that updates progress every few hundred ms using functional updater to avoid stale closures.
8. The or effect watches when all percentages reach 100% and flips status to ready.
9. A cleanup function removes timer when status changes or component unmounts.
10. If you run in StrictMode you may see an extra effect cycle – this is intentional dev‑mode double rendering check and does not affect production performance.

常见错误与排查

建立时提示找不到 tsconfig.json

• If you started with JavaScript template but used “tsc -b && vite build”。you’ll get this error because TypeScript expects a tsconfig.json file. Eir remove “tsc” from your script or add a minimal tsconfig if you truly want TS support.
  💡Tip: Keep JavaScript projects purely JS or switch fully to TS – don’t mix m halfway through.

  Note: The above snippet was unintentionally truncated due to formatting issues—ensure your package scripts match template you chose.

  ESLint 成功，但 JSX 根本没有被检查

  • If your ESLint config only targets *.tsx files,n *.jsx files are ignored. For JavaScript React projects make sure `files:` is included and enable appropriate parser options for JSX. • Test by adding an undefined variable in a .jsx file n run `npm run lint`. If it reports an error you’re good. • If no errors appear after adding test code n adjust pattern accordingly.

  点击按钮后立即执行，或者完全没反应

  • A common mistake is writing ``. This invokes function immediately during render instead of passing it as callback. • Correct usage: ` • Also ensure that `handleLoad` does not contain any side effects that block rendering . In our example we only update state so it’s safe.

  进度数据变了界面却没有更新

  • You must never mutate state directly . Instead always create new array/object references using functional updater: ` • Verify that `setProgressItems` was called at least once after state change. • Check that your comparison key matches exactly – mismatched keys mean React keeps old components unchanged.

  WebGPU 检测始终失败

  • a) ‘navigator.gpu’ ;b) ‘navigator.gpu.requestAdapter’;c) ‘if page served over HTTPS or localhost’. Non-secure contexts block access even when browsers claim support.

  从界面原型走向真实模型加载

  The current demo intentionally mocks progress via a timer. When plugging in real inference logic you can swap out pieces step by step:

  • Treat timer callback as placeholder for library download callbacks—update progressItems keyed by file name inside those callbacks.
  • "loading" before start and "ready" on success or "error" on failure storing readable message. lI> ・Use a WebWorker for heavy inference so UI stays responsive—post messages back to main thread which updates React state. lI> ・Add cancellation logic so navigation away or model switch aborts pending fetches/workers. lI> ・Don’t rely solely on download percent. Real init may involve “reading cache”。“compiling graph”,“warming up”. Add separate phase labels as needed. lI> ・Large models require careful storage handling—check device memory limits and consider progressive loading. lI>

  These incremental changes preserve core principle: Your UI should only display what external processes report via state—never guess what’s happening internally.