Web 图形与 3D / 系统课时
搭建 Vite 开发服务与热更新
搭建 Vite 开发服务与热更新
这一篇把 Vite 与 TypeScript 配成 WebGPU 的本地开发入口:启动后能在浏览器检查 GPU 适配器、从独立 WGSL 文件加载着色器,保存文件即可看到变化,同时在终端持续发现类型错误,最后验证生产构建。
学习目标
- 使用 Vite 的
vanilla-ts模板启动本地服务。 - 把 WGSL 着色器和静态资源放到合适目录,并完成浏览器端接入。
- 区分热模块替换与整页重载,使用 TypeScript 检查和构建命令验收。
初始化项目并启动服务
示例采用 Vite 8 与 TypeScript 6。先确认 Node.js 满足 Vite 要求:20.19+ 或 22.12+,推荐仍在维护的 Node.js 22/24 LTS。使用 npm 7 及以上版本时,模板参数前需要 --。
node --version
npm --version
# 无框架模板,适合直接练习浏览器 WebGPU API
npm create vite@latest webgpu-lab -- --template vanilla-ts
cd webgpu-lab
npm install
npm install -D typescript@^6.0.4
npm run dev预期结果:终端出现本地地址,以下只摘录地址部分;实际版本号、耗时及端口可能不同。
Local: http://localhost:<PORT>/在浏览器打开终端给出的地址,能看到 Vite 初始页面。默认端口通常为 5173,被占用时可能改变。TypeScript 6.0.4 及以上的 6.x 版本提供较完整的 WebGPU DOM 类型声明;保留模板 tsconfig.json 中的 types: ["vite/client"],供 ?raw 导入获得类型支持。
放置 WGSL 与静态资源
Vite 把 src/ 内的文件纳入模块依赖图,适合放着色器源码;public/ 中的资源按原样复制,适合放无需模块处理的纹理文件。使用编辑器建立如下路径,现阶段无需额外安装 WGSL 加载插件。
| 路径 | 用途 |
|---|---|
src/main.ts |
浏览器入口,执行 WebGPU 能力检测 |
src/shaders/check.wgsl |
WGSL 源码,经 ?raw 导入为字符串 |
src/style.css |
页面样式,可观察 CSS 热更新 |
public/textures/ |
后续原样提供纹理,例如 /textures/noise.png |
新建 src/shaders/check.wgsl,写入一个最小合法的计算着色器。它只是待编译的源码,不会自己执行计算。
// 最小计算入口:仅用于检查 WGSL 是否能编译
@compute @workgroup_size(1)
fn main() {}这里的 @workgroup_size(1) 表示每个工作组有一个调用。当前尚未创建计算管线或提交调度;真正的验证由浏览器中的 createShaderModule() 完成。
接入浏览器与着色器检查
保留模板 index.html 中已有的 #app 容器,把 src/main.ts 完整替换为以下代码。?raw 是 Vite 内建的字符串导入方式,不是 WebGPU API。
import './style.css';
import wgslSource from './shaders/check.wgsl?raw';
const app = document.querySelector<HTMLDivElement>('#app');
if (!app) throw new Error('找不到 #app 容器');
async function start(root: HTMLDivElement): Promise<void> {
if (!navigator.gpu) {
root.textContent = 'WebGPU 不可用:检查浏览器和安全上下文';
return;
}
const adapter = await navigator.gpu.requestAdapter();
if (!adapter) {
root.textContent = '没有可用的 GPU 适配器';
return;
}
const device = await adapter.requestDevice();
// 只检查着色器编译,不创建管线或执行计算
const shader = device.createShaderModule({ code: wgslSource });
const info = await shader.getCompilationInfo();
const firstError = info.messages.find(m => m.type === 'error');
if (firstError) throw new Error(firstError.message);
const heading = document.createElement('h1');
heading.textContent = 'WebGPU 就绪';
const preview = document.createElement('pre');
// 显示源码时使用文本节点,而不是插入 HTML
preview.textContent = wgslSource;
root.replaceChildren(heading, preview);
}
void start(app).catch((error: unknown) => {
app.textContent = `初始化失败:${String(error)}`;
});预期结果:支持 WebGPU 且可获取设备的浏览器显示“WebGPU 就绪”,其下出现 WGSL 源码;不支持时显示对应提示。这个结果验证设备申请与 WGSL 编译成功,不代表已经发生计算或绘图。
测试文件更新与类型检查
先在 check.wgsl 的注释中增加几个字,保存后查看页面中的源码是否变化;再修改 src/style.css 的背景色。CSS 通常通过 HMR 原位替换;没有声明接收边界的 TypeScript 或 WGSL 依赖更新可能退化为整页重载,但无需手动刷新。页面重载会重新申请设备,并非保留原来的 GPU 资源。

Vite 开发服务主要转译 TypeScript,并不代替 tsc 做类型检查。在另一个终端、项目根目录运行持续检查:
npx tsc --noEmit --watch预期输出(省略时间戳):
Found 0 errors. Watching for file changes.验证报错链路时,可暂时把 main.ts 中 heading.textContent = 'WebGPU 就绪'; 改成 heading.textContent = 42;。检查终端应报告 TS2322 类型不兼容;恢复字符串后错误消失。保存后页面正常更新并不等于类型检查通过。
验收构建并处理失败
停止或另开终端,在项目根目录执行生产构建,再使用预览服务器验证 dist/ 产物。Vite 的 vanilla-ts 模板默认通过 tsc && vite build 构建,类型错误会阻止构建完成。
npm run build
npm run preview预期结果:dist/ 目录生成,终端先显示构建成功,再给出预览地址。下列是两条命令输出的关键部分;<TIME> 与 <PORT> 按实际环境变化。
✓ built in <TIME>
Local: http://localhost:<PORT>/如果启动时报 Node.js 版本不兼容,升级 Node.js 后重新安装依赖;如果编辑器提示 navigator.gpu 或 WebGPU 类型缺失,先运行 npx tsc --version,确认 TypeScript 至少为 6.0.4(本例已显式安装)。如果网页显示“WebGPU 不可用”,检查浏览器是否支持 WebGPU,以及是否通过 localhost 或 HTTPS 等安全上下文访问。普通远程 HTTP 地址即使能打开 Vite 页面,也不代表能使用 WebGPU。
最终验收应同时满足:修改 WGSL 后页面自动显示新源码、修改 CSS 后样式更新、类型检查无错误、npm run build 成功。