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 及以上版本时,模板参数前需要 --。

bash
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

预期结果:终端出现本地地址,以下只摘录地址部分;实际版本号、耗时及端口可能不同。

text
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
// 最小计算入口:仅用于检查 WGSL 是否能编译
@compute @workgroup_size(1)
fn main() {}

这里的 @workgroup_size(1) 表示每个工作组有一个调用。当前尚未创建计算管线或提交调度;真正的验证由浏览器中的 createShaderModule() 完成。

接入浏览器与着色器检查

保留模板 index.html 中已有的 #app 容器,把 src/main.ts 完整替换为以下代码。?raw 是 Vite 内建的字符串导入方式,不是 WebGPU API。

ts
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 开发服务的文件更新和类型检查数据流

Vite 开发服务主要转译 TypeScript,并不代替 tsc 做类型检查。在另一个终端、项目根目录运行持续检查:

bash
npx tsc --noEmit --watch

预期输出(省略时间戳):

text
Found 0 errors. Watching for file changes.

验证报错链路时,可暂时把 main.ts 中 heading.textContent = 'WebGPU 就绪'; 改成 heading.textContent = 42;。检查终端应报告 TS2322 类型不兼容;恢复字符串后错误消失。保存后页面正常更新并不等于类型检查通过。

验收构建并处理失败

停止或另开终端,在项目根目录执行生产构建,再使用预览服务器验证 dist/ 产物。Vite 的 vanilla-ts 模板默认通过 tsc && vite build 构建,类型错误会阻止构建完成。

bash
npm run build
npm run preview

预期结果:dist/ 目录生成,终端先显示构建成功,再给出预览地址。下列是两条命令输出的关键部分;<TIME> 与 <PORT> 按实际环境变化。

text
✓ 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 成功。

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

目录与阅读设置

阅读设置

17

记录一个想法

搭建 Vite 开发服务与热更新

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

登录哪都通