WebGPU 着色器不用手写 WGSL 了，TypeGPU 让你用 TypeScript 搞定

写过 WebGPU 的开发者应该都体验过手写 WGSL（WebGPU Shading Language）的痛苦：着色器代码和 JavaScript 完全割裂，类型信息无法共享，一旦数据结构改了，两边都要手动同步，运行时才能发现类型不匹配的问题。

TypeGPU 尝试解决这个问题。它是一个基于 WebGPU 的 TypeScript 工具库，核心能力是让你用 TypeScript 编写着色器逻辑，自动生成对应的 WGSL 代码，并在 JavaScript/TypeScript 和 GPU 代码之间提供端到端的类型安全。

它解决了什么问题

原生 WebGPU 开发有几个绕不开的摩擦点：

1. JS 和着色器的类型断层

在原生 WebGPU 中，你在 JavaScript 里定义的数据结构（比如一个包含位置和颜色的顶点格式），需要在 WGSL 着色器里再手写一遍对应的 struct。两者之间没有任何类型关联，改了一边，另一边不会有任何提示。

TypeGPU 的做法是：用 TypeScript 定义一次数据结构，这个定义同时作为 JS 侧的类型约束和着色器代码的生成依据，两边始终保持一致。

2. 无效 GPU 状态难以被提前发现

WebGPU 的 Buffer 绑定、Pipeline 配置等如果写错，通常只在运行时（甚至只在 GPU 执行时）才会暴露问题，调试成本很高。TypeGPU 的设计目标是"让无效状态难以被表达"——通过 TypeScript 的类型系统，在编写代码阶段就阻止错误配置。

3. 着色器函数无法在 JS 侧直接测试

原生 WGSL 函数只能在 GPU 上执行，测试和调试都很不方便。TypeGPU 的着色器函数支持三种执行模式：直接在 JavaScript 中调用（用于测试）、生成 WGSL 代码、或直接在 GPU 上执行。

核心特性

用 TypeScript 定义着色器函数

TypeGPU 提供了 tgpu.fn 等 API，让你用接近普通 TypeScript 的语法编写着色器逻辑：

import tgpu from 'typegpu';
import * as d from 'typegpu/data';
 
const addVectors = tgpu.fn([d.vec3f, d.vec3f], d.vec3f)((a, b) => {
  return d.vec3f(a.x + b.x, a.y + b.y, a.z + b.z);
});
 
// 可以直接在 JS 中调用（用于测试）
const result = addVectors(d.vec3f(1, 2, 3), d.vec3f(4, 5, 6));
 
// 也可以编译为 WGSL 并在 GPU 上执行

类型安全的数据结构

用 typegpu/data 定义数据结构，这个定义在 JS 和着色器两侧同时生效：

import * as d from 'typegpu/data';
 
// 定义一次，两侧共享
const Vertex = d.struct({
  position: d.vec4f,
  color: d.vec4f,
});
 
// TypeScript 自动推断出正确的类型
type VertexType = d.Infer<typeof Vertex>;
// { position: { x: number, y: number, z: number, w: number }, color: ... }

模块化，可以按需引入

TypeGPU 不是一个全量框架，而是一组可以独立使用的原语。你可以只引入类型定义部分来增强现有的 WebGPU 代码，也可以逐步采用更多功能，而且随时可以"退出"到原生 WebGPU API，不存在厂商锁定的问题。

安装与配置

安装

npm install typegpu
npm install --save-dev @webgpu/types

TypeScript 配置

在 tsconfig.json 中添加 WebGPU 类型支持：

{
  "compilerOptions": {
    "types": ["@webgpu/types"]
  }
}

着色器功能需要构建插件

如果需要使用着色器函数（tgpu.fn）自动生成 WGSL 的能力，还需要安装构建插件：

npm install --save-dev unplugin-typegpu

以 Vite 为例，在 vite.config.ts 中配置：

import typeGPU from 'unplugin-typegpu/vite';
 
export default {
  plugins: [typeGPU()],
};

适合哪些场景

TypeGPU 文档里对适用场景有明确的说明，以下几类比较适合：

  • GPU 加速计算：物理模拟、粒子系统、流体模拟等需要大量并行计算的场景
  • 自定义渲染器：不想套用 Three.js 等框架，需要完全控制渲染管线
  • AI 推理：在浏览器端运行轻量级模型，利用 GPU 加速推理过程
  • 跨平台 GPU 开发：通过 react-native-wgpu，同一套 TypeGPU 代码也可以在 React Native 中运行

不太适合的场景：通用的 3D 网站（展示型的三维场景、产品展示等），这类场景 Three.js、Babylon.js 这些成熟框架更合适，TypeGPU 的类型安全优势在这里体现不出来。

已有真实项目在用 TypeGPU，包括 ComfyUI（生成式 AI 工具）、Vivarium（细胞自动机工具库）和 wayfare（游戏引擎）。

写在最后

TypeGPU 的核心价值不是"让 WebGPU 更简单"，而是"让 WebGPU 开发更可维护"。它不会帮你屏蔽 GPU 编程的复杂性，你仍然需要理解 WebGPU 的渲染管线、缓冲区绑定和着色器概念，但它帮你把 TypeScript 的类型系统延伸到了 GPU 代码里，减少了因为类型不匹配导致的运行时错误。

对于已经在使用 WebGPU 的团队，TypeGPU 的模块化设计允许渐进式引入，不需要一次性重写现有代码。官方文档提供了大量可在 StackBlitz 上直接运行的交互示例，可以先跑起来感受一下再决定是否引入。

GitHub 项目地址：https://github.com/software-mansion/TypeGPU (opens in a new tab) 官方文档：https://docs.swmansion.com/TypeGPU/ (opens in a new tab)

搭建 threejs 的环境