不想为 Shader 搬一整套 Three.js：vgpu 使用手记
痛点先摆出来
你要是做过 Web 3D，大概率躲不开 Three.js。场景、模型、材质、光照、后处理，它确实是这个领域的事实标准。
但问题也出在这里：很多时候你根本不需要一个「3D Engine」。
你只是想跑一个全屏 Shader、做一组粒子效果、写一段流体模拟，或者丢一段 GPU Compute。结果打开项目，three 这个包已经躺在 package.json 里，几百 KB 的体积跟着进了首屏 bundle，而用到的可能只是 RawShaderMaterial + PlaneGeometry + OrthographicCamera 那三五行代码。
这不是你的问题。这是 WebGPU 领域从一开始就缺一块拼图：一个不做三维场景管理的轻量 GPU 抽象层。
Vercel 最近开源的 vgpu，想补的就是这块。
定位：25 KB 的 effect，而不是 500 KB 的 engine
vgpu 是一个基于 TypeScript 的 WebGPU 库，定位是 Shader、3D、GPU Compute、Tensor、神经网络和数学可视化。它最初是 Vercel 官网用来渲染高性能 Shader 效果的内部工具，现在独立开源了。
官方有句话说得非常直接：
Ship a 25 KB effect, not a 500 KB engine.
这句话就是对它的整个设计哲学最精确的概括。
一个完整的 Fullscreen Effect 体积预算是 25KB gzip。这个数字怎么理解？它不是「运行时动态加载体积」，而是说：如果你的目的是做一个 WebGPU 特效，那么引入 vgpu 的全部成本就在这个量级。对比是隐性的——某个常见的 3D Engine 光是核心库的体积就已经是它的十几倍，而且你未必用得上其中 80% 的模块。
当然要说得严谨一点：25KB 是库本身的体积预算，不是你的业务代码总预算。WGSL Shader、纹理、模型、你的业务逻辑，这些照常单独计算。所以正确的解读是：vgpu 把「跑一个 GPU 特效」的框架成本压到了 25KB 这个水平，剩下的账你自己算。
原生 WebGPU 的门槛，确实是高
原生 WebGPU 的问题不是难，而是琐碎。
要画一个三角形：创建 Adapter、请求 Device、配置 CanvasContext、编 Shader Module、建 Pipeline、声明 BindGroupLayout、分配 Buffer、设置 Vertex State、写 WGSL……每一步都有样板代码，每一条样板代码都是知识盲区。
vgpu 做的事情，是在 WebGPU 之上封装一层更薄的抽象。
核心流程被压缩成了四步：
init() → surface() → effect() → frameLoop()
一个最小可运行的示例：
import { init, surface, effect, frameLoop } from 'vgpu';
const gpu = await init();
const canvas = document.querySelector('canvas')!;
const target = surface(gpu, canvas);
const shader = effect(gpu, myShader);
frameLoop(gpu, (frame) => {
frame.pass(target, shader);
});
然后剩下的事情就是写 WGSL。
还有一点值得注意：.wgsl 文件支持像 ES Module 一样 import / export，Shader 的 binding、type、layout 这些由 vgpu 自动处理。这意味着你不用手动维护 BindGroup 和 Buffer 的对应关系。
跨运行时的设计，比想象中激进
vgpu 有另一个不太常见的设计：同一套 API，跨三个运行时。
- Browser：直接用原生 WebGPU。
- Node.js：
vgpu/node基于 Dawn 提供 headless GPU Device，没有浏览器也能执行 GPU 任务。 - Test / CI：
vgpu/mock，很多测试根本不需要真实 GPU。
这个设计的意义不止是「方便」。
它意味着 Shader 和 GPU Compute 代码终于可以进入 Node 脚本、自动化测试 和 CI 流水线。GPU 相关逻辑不再是一个只能在浏览器里手动验证的黑盒。你可以在 push 前自动跑一遍 shader 编译检查，甚至直接跑 GPU 数值计算相关的测试。
已经验证过的能力
官网的示例列表能说明一些问题：
- Black Hole
- Earth
- Interactive Fluid
- FFT Ocean
- Raymarched Fractal
- Glass Fractal
- Transmission
- Radiance Cascades
以及一个 Instanced Rendering 示例，同时渲染 125,000 个独立动画立方体。
AI 场景也有涉足。官方给出了 Depth Estimation、MNIST Classifier、Air Painting 等 Demo，把 ONNX Runtime Web + WebGPU + vgpu 串联了起来。
所以它不只是「一个做网页特效的库」。Rendering、Compute、3D、Tensor、Machine Learning，都可以进同一套 GPU Workflow。
而且它考虑到开发者的实际体验，提供了 CLI：
# 搜索 ray marching 相关示例
npx vgpu examples search "raymarching"
# 拉取完整示例到本地
npx vgpu examples pull --out ./example
以快速找现成案例这件事来说，这就友好太多了。
给 AI Agent 留的接口
Vercel 连 AI 开发流程都考虑到了。仓库里提供了 agents.md、llms.txt、llms-full.txt、CLI、Examples API 和 MCP。
Coding Agent 可以自己完成整个闭环：
# 查文档
npx vgpu docs find effect
# 搜案例
npx vgpu examples search "fluid"
# 检查 WGSL 是否合法
npx vgpu check ./shader.wgsl
流程就是：查文档 → 找 Demo → 拉源码 → 写 WGSL → 检查 Shader。
对 Codex、Claude Code 这类工具来说，这套设计非常务实——因为 AI Agent 最不适合做的就是在文档里瞎翻。
适合什么，不适合什么
适合
- 全屏 Shader、粒子特效、流体动画、Ray Marching 这种「画面优先」的工作
- GPU Compute，包括图像处理、数据并行计算、数学可视化
- 浏览器 AI 推理的渲染/计算部分（ONNX Runtime Web + vgpu）
- Node 环境或 CI 里执行 GPU 任务
- 想用 AI Agent 辅助开发 WebGPU 项目的场景
不适合
- 复杂三维场景：模型加载、动画骨骼、相机控制、碰撞检测、物理模拟等完整场景编排需求
- 需要场景图（Scene Graph）管理、材质系统、后处理链路的工程化项目
- 需要 WebGL 兼容或回退方案的项目——vgpu 是 WebGPU 库，原文未提供 WebGL 兼容方案
和 Three.js 的边界
Three.js 是你的 3D 场景「编辑器」，它是完整的引擎层。而 vgpu 是 GPU 管线的「封装修」，两者服务不同的问题。
有重叠的部分，但重叠不等于替代：
- 如果你要做的是全屏 Shader 特效果，Three.js 确实能实现，但你被迫接受它的场景图、材质实例、渲染循环、相机抽象。这些在这个场景下是「税收」——你不一定用它，但你得带着它过日子。vgpu 不碰这些抽象，直接给你最薄的管线。
- 如果你要做的是有场景空间关系、有模型资源管理、有复杂交互的 3D 应用，那个领域 vgpu 不是来替代 Three.js 的，它在这个领域没有什么可替代的——它根本不做场景管理。
这个边界很清晰：三维场景组装，找 Three.js；GPU 原语操作，找 vgpu。
值不值得用？
WebGPU 一直有个尴尬处境：原生 API 太底层，完整 3D Engine 又太重，中间缺少一个「薄、快、只做 GPU 该做的事」的选项。
vgpu 填补的正是这个位置：25KB gzip 的体积、TypeScript、Typed WGSL、Browser/Node/CI 跨运行时、还给 AI Agent 留了完整的工具链。
如果你的任务里只是想要特效、Shader 或 GPU Compute，不想背一个 3D Engine 的壳，这个项目值得翻一翻。至于生产环境稳定性，这个项目刚开源不久，长周期大规模场景下的表现还需要观察，原文也没有提供生产环境验证数据。
渠道信息：
- 官网：
vgpu.sh - Examples：
vgpu.sh/examples - GitHub：
vercel-labs/vgpu