跳到主要内容

创建日期：2026-09-06 ｜ 最近更新：2026-09-06 内容基准：vgpu v0.4.0（npm latest 实测为 0.4.0）＋ 本地源码 vercel-labs/vgpu。文中命令与输出逐字摘自随包 CLI 与官方文档，未额外改写。

vgpu 是什么：为 Agent 而生的 WebGPU 库（入门）

vgpu 是一个 Vercel Labs 出品的 TypeScript WebGPU 库（源码 github.com/vercel-labs/vgpu）。官方一句话定位：

vgpu is a small, composable WebGPU library — typed shader imports, a tiny gpu-first API, and the same code running in the browser, headless Node, and your test suite.

即：一套 API，同一份代码，能在三种环境跑——浏览器 canvas、Node.js 无头渲染（基于 Dawn）、测试（确定性 mock）。shader 文件（.wgsl）像 TypeScript 模块一样被 import/export，编译期做反射，不需要手写 binding 声明。

为什么在 code 栏目单独开一个子项目​

对纯图形/前端而言，它是个"又一个 WebGPU 封装"；真正值得记录的是它把 “面向 coding agent 的开发者工具” 做到了极致：

  • 文档随包：CLI 把整份 API reference + 指南打包进 npm 包，离线可查、版本与代码严格同步，解决"文档和装上的版本漂移"这个老问题；
  • CLI 自举：npx vgpu 一跑就打印"自己怎么被读"，专门写给 agent 看；
  • Skill + MCP：官方发布了一个 version-neutral 的 Skill 路由器（不背 API 快照，教你查随包文档），还提供 hosted + local 两种 MCP server；
  • 示例可信：examples 走只读、sha256 校验的不可变 artifact，CLI/MCP 永不执行拉下来的示例代码。

这正好串起本博客已有的两条线：docs/code 的 MCP 入门 与 docs/agent 的 AI Agent 课程。对想自己"做一个 agent-first 库/文档站"的人，它是一份非常完整的活样例。

心智模型：四个词记住它​

关键词含义
多运行时浏览器 WebGPU / Node.js（Dawn，无头）/ mock（确定性，测试用），同一套公开 API。import ... from "vgpu"、"vgpu/node"、"vgpu/mock"
WGSL 模块化.wgsl 像 TS 模块一样 import/export；vgpu 编译期做反射解析引用图，最终变成普通 WGSL。@vgpu/wgsl-std 提供现成声明
单一 Gpu 上下文init() 返回唯一句柄；draw/effect/frame/surface/target/... 都以它为第一个参数。无隐藏全局状态
显式帧frame(gpu, cb) 里明确调用 pass/clear/draw，不走隐式场景图状态机

顺带一提的体量设计：一个完整全屏 effect 产物 gzip 后约 25 KB，由 CI 卡预算。

快速上手：三条路任选一条​

路径 A（最推荐，本系列主角）：把它交给 coding agent​

npx vgpu

就这么一句。 裸命令会打印它自己的使用指南——从 agent 入门 vgpu docs cat getting-started.md 开始，含探索/检索所有 reference、guide、error code 的工具。agent 拿到这句就知道接下来干什么。想再进一步可以 npx skills add vercel-labs/vgpu 装官方 skill，或 npx -y add-mcp https://vgpu.sh/api/mcp -g 连 hosted MCP——机制拆解见本系列第 1、2 篇。

路径 B：浏览器渲染一帧渐变​

npm install vgpu
import { init, effect, surface } from "vgpu";
import gradientSource from "./gradient.wgsl";

const gpu = await init();
const canvas = document.querySelector("canvas")!;
const canvasSurface = surface(gpu, canvas);
const gradient = effect(gpu, gradientSource);

gradient.draw(canvasSurface); // 立即渲染
// gradient.wgsl
@fragment fn fs_main(@location(0) uv: vec2f) -> @location(0) vec4f {
  return vec4f(uv, 0.4, 1.0);
}

.wgsl 文件的打包需要在构建器里加 loader：Next.js 用 @vgpu/wgsl/loader-webpack，Vite 用 @vgpu/wgsl/loader-vite；再加一行 /// <reference types="@vgpu/wgsl/wgsl-types" /> 让 TS 把 .wgsl import 识别成字符串。

路径 C：Node.js 无头渲染（无需浏览器/GPU）​

同一套 API，改从 vgpu/node 导入、渲染进离屏 target，再把像素读回来：

import { init, effect, target } from "vgpu/node";

const gpu = await init();
const colorTarget = target(gpu, { size: [256, 256] });
const src = `
  @fragment fn fs_main(@location(0) uv: vec2f) -> @location(0) vec4f {
    return vec4f(uv, 0.4, 1.0);
  }
`;
effect(gpu, src).draw(colorTarget);
const pixels = await colorTarget.read(); // RGBA 字节
gpu.dispose();

Node 环境在 Linux 上能自动解析 Dawn 预编译二进制；缺 GPU/驱动的机器跑一次 npx vgpu install-software-renderer 就能用 CPU 渲染。任何机器动手前先跑 npx vgpu doctor——它会真渲染一帧并给出 JSON 结论与修复建议。测试场景想零 GPU 用 vgpu/mock。

本文命令的“可验证性”说明​

写这篇时我在沙箱里读了本地 vercel-labs/vgpu 源码与随包文档（v0.4.0），但未在沙箱内执行 npx vgpu（外部包执行需授权）。因此文中一切命令、帮助文本都逐字引自 v0.4.0 仓库源码 / 官方文档；裸命令 npx vgpu 的输出文本摘自 packages/vgpu/bin/vgpu.js 的 help 常量。读者在任意联网终端可直接复现验证。

本系列路线图​

篇主题状态
0入门：是什么 + 三条上手路径（本文）✅
1让 Agent 用 vgpu：CLI 自举 + 官方 Skill 的版本纪律机制✅
2MCP：hosted HTTP vs local stdio、工具、示例下载边界、各客户端接入✅
3CLI 全命令 + 可信示例工作流（examples API / sha256）✅
4+WebGPU 渲染 API 深挖（concepts：frames/effects/passes/bundles…）待写

参考与来源​