企业官网建设流程全解析

1. 为什么"又一个渲染引擎"这个定位本身就是个陷阱

先把结论摆在前面：ZenFG 不是拿来跟 Three.js、Babylon.js 或者 wgpu 官方示例抢饭碗的。如果你抱着"我要找一个开箱即用的 WebGPU 渲染引擎"的心态点进来，大概率会失望——它没有内置的 PBR 材质库，没有场景编辑器，没有一键加载 glTF 然后自动帮你把阴影、后处理全配好的那种"全家桶"体验。

它做的事情，用一句话概括：把一帧渲染里那些乱七八糟的 Pass 编排、资源依赖、生命周期管理，抽象成一张可以动态组合的图。这张图就是 FrameGraph。

我最早接触 FrameGraph 这个概念是在做离线渲染和主机端引擎的时候。那时候团队里有个共识：渲染管线一旦超过十几个 Pass，靠手写renderPassA(); renderPassB(); renderPassC();这种线性调用，维护成本会指数级上升。你改一个后处理顺序，可能要把整个render()函数重排一遍；你想临时关掉某个 Pass 看效果，得手动注释掉一堆资源绑定代码；你想让两个 Pass 共享一张中间纹理，得自己小心翼翼地管理它的创建和销毁时机。

WebGPU 的出现让这个问题变得更尖锐。因为 WebGPU 的 API 设计比 WebGL 严格得多——GPUTexture、GPUBuffer、GPURenderPassEncoder这些对象都有明确的生命周期，你不能像 WebGL 那样随便gl.createTexture()然后到处传。资源管理一旦松散，就会出各种"纹理已销毁但还在被引用"的报错。而 FrameGraph 恰好是解决这类问题的成熟范式。

所以 ZenFG 的定位很清晰：它是一层薄薄的、可组合的 FrameGraph 抽象，架在 wgpu 之上，帮你把 Pass 编排和资源依赖管起来，但把具体的渲染逻辑完全交还给你。你可以用它来搭一个延迟渲染管线，也可以用它来做一个纯计算的后处理链，甚至可以用它来组织非图形类的 GPU 计算任务。它不替你做决定，只帮你把"决定"组织得更有条理。

这篇文章我会从几个角度拆：FrameGraph 到底解决了什么本质问题、ZenFG 的核心抽象长什么样、怎么用它搭一条真实的管线、以及我在实际使用中踩过的那些坑。适合已经对 WebGPU 有基本了解、但被 Pass 编排折磨过的开发者。

2. FrameGraph 到底在解决什么问题：从"手写 Pass 链"到"声明式依赖"

2.1 手写渲染管线的三个典型痛点

先看一段典型的、没有 FrameGraph 的 WebGPU 渲染代码大概长什么样：

// 伪代码，展示手写 Pass 链的典型结构 const shadowTexture = device.createTexture({ ... }); const gbufferAlbedo = device.createTexture({ ... }); const gbufferNormal = device.createTexture({ ... }); const gbufferDepth = device.createTexture({ ... }); const hdrTarget = device.createTexture({ ... }); const bloomTarget = device.createTexture({ ... }); // Pass 1: 阴影 const shadowPass = encoder.beginRenderPass({ ... }); shadowPass.setPipeline(shadowPipeline); shadowPass.setBindGroup(0, shadowBindGroup); shadowPass.draw(...); shadowPass.end(); // Pass 2: G-Buffer const gbufferPass = encoder.beginRenderPass({ ... }); gbufferPass.setPipeline(gbufferPipeline); gbufferPass.setBindGroup(0, gbufferBindGroup); gbufferPass.draw(...); gbufferPass.end(); // Pass 3: 光照 const lightingPass = encoder.beginRenderPass({ ... }); // ... 绑定 gbufferAlbedo, gbufferNormal, gbufferDepth lightingPass.end(); // Pass 4: Bloom // ... 又是一堆绑定 // Pass 5: 合成 // ... 最后输出到 canvas

这段代码的问题不在于它"错"，而在于它脆弱。具体来说有三个痛点：

第一，资源生命周期和 Pass 顺序强耦合。你想调整 Bloom 在光照之前还是之后，不只是移动几行代码的事——bloomTarget的创建时机、它依赖的输入纹理、以及后续合成 Pass 对它的引用，全都要跟着改。一旦管线复杂到二十几个 Pass，这种改动就是灾难。

第二，临时资源的创建和销毁没有统一管理。上面每个createTexture都是手动调的，但什么时候destroy()？如果某个 Pass 被临时禁用，它对应的纹理还创建吗？如果两个 Pass 可以共享一张中间纹理，怎么知道它们能共享？这些问题在手写模式下全靠人脑记。

第三，无法做全局优化。比如你想知道"这一帧到底创建了多少张纹理、总显存占用多少"，或者"哪些 Pass 实际上没有贡献到最终输出、可以裁掉"，手写模式下你只能靠肉眼和调试工具。

2.2 FrameGraph 的核心思想：把"执行"变成"声明"

FrameGraph 的思路其实借鉴了编译器里的数据流图和惰性求值。你不再直接写"先执行 A，再执行 B"，而是声明：

• 我有哪些资源（纹理、缓冲区）
• 每个 Pass读取哪些资源、写入哪些资源
• 最终我要的输出是什么

然后 FrameGraph 根据这些声明，自动推导出：

• Pass 的执行顺序（拓扑排序）
• 哪些资源是临时的、可以复用内存
• 哪些 Pass 是"死代码"、可以裁掉
• 资源的创建和销毁时机

这个思路在 Frostbite、Frostbite 的 FrameGraph 演讲里被讲得很透，后来 Unreal 的 RDG（Render Dependency Graph）也是同一套哲学。ZenFG 把这套东西带到了 WebGPU 生态里。

2.3 为什么是"可组合"而不是"全功能"

这里要特别说一下 ZenFG 标题里"可组合"三个字的分量。很多渲染引擎的 FrameGraph 是内置且封闭的——你只能用引擎提供的 Pass 类型，想加自定义 Pass 得改引擎源码。ZenFG 反过来：它只提供 FrameGraph 的骨架，Pass 的具体实现完全由你写。

这意味着你可以：

• 用 ZenFG 组织一个纯 WebGPU 原生的管线，不引入任何额外抽象
• 把 ZenFG 嵌到现有的渲染框架里，只让它管 Pass 编排这一层
• 针对不同场景（实时渲染、离线烘焙、GPU 计算）复用同一套 FrameGraph 逻辑

这种"薄"的设计，代价是你得自己写更多代码，但换来的是不被框架绑架。我个人在选型时越来越偏好这种风格——框架越厚，出问题时越难定位到底是框架的锅还是自己的锅。

3. ZenFG 的核心抽象：Resource、Pass 和 Graph 三者怎么咬合

3.1 Resource：不只是纹理和缓冲区

在 ZenFG 里，Resource 是一个比GPUTexture更宽的概念。它可以是：

• 纹理资源：渲染目标、深度缓冲、G-Buffer 附件
• 缓冲区资源：顶点缓冲、Uniform 缓冲、Storage 缓冲
• 外部资源：来自 canvas 的 swapchain 纹理、外部传入的纹理
• 虚拟资源：只存在于图里、由 FrameGraph 决定实际分配的中间资源

关键区别在于虚拟资源。你声明"我需要一张 RGBA16F 的中间纹理"，但具体这张纹理什么时候创建、能不能和别的资源复用同一块显存，由 FrameGraph 在编译阶段决定。这就是 FrameGraph 做内存优化的基础。

// 声明一个虚拟纹理资源 const hdrTarget = graph.createResource({ name: 'hdrTarget', type: 'texture', desc: { size: { width: 1920, height: 1080 }, format: 'rgba16float', usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING } });

注意这里没有直接调device.createTexture。真正的创建发生在 FrameGraph 编译之后，由它统一分配。

3.2 Pass：声明读写，不声明顺序

一个 Pass 在 ZenFG 里的定义，核心是读集和写集：

graph.addPass({ name: 'lightingPass', reads: [gbufferAlbedo, gbufferNormal, gbufferDepth, shadowMap], writes: [hdrTarget], execute: (encoder, resources) => { const pass = encoder.beginRenderPass({ colorAttachments: [{ view: resources.hdrTarget.createView(), loadOp: 'clear', storeOp: 'store', clearValue: { r: 0, g: 0, b: 0, a: 1 } }] }); pass.setPipeline(lightingPipeline); pass.setBindGroup(0, createLightingBindGroup(resources)); pass.draw(3); pass.end(); } });

这里最关键的一点：你没有指定这个 Pass 在哪个 Pass 之后执行。FrameGraph 会根据reads和writes自动推导依赖关系。lightingPass读了gbufferAlbedo，而某个gbufferPass写了它，那么gbufferPass自然排在前面。

这种声明式的好处是，当你增删 Pass 时，顺序会自动调整。你不需要维护一个"Pass 执行顺序表"。

3.3 Graph：编译、裁剪、执行

Graph 是容器，也是编译器。它的生命周期分三个阶段：

声明阶段：你往 graph 里加资源、加 Pass，此时什么都没真正执行。

编译阶段：FrameGraph 做几件事——拓扑排序确定执行顺序、分析资源生命周期做内存复用、裁剪掉不影响最终输出的 Pass。

执行阶段：按编译结果依次调用每个 Pass 的execute，并把实际分配的资源传进去。

// 声明 const graph = new FrameGraph(device); const shadowMap = graph.createResource({ ... }); const gbuffer = graph.createResource({ ... }); // ... 加一堆 Pass // 编译 const compiled = graph.compile({ outputs: [finalColor] // 告诉它最终要什么 }); // 执行 const encoder = device.createCommandEncoder(); compiled.execute(encoder); device.queue.submit([encoder.finish()]);

编译阶段是 FrameGraph 真正体现价值的地方。我实测过一个场景：一条有 18 个 Pass 的管线，其中 4 个 Pass 因为调试开关被临时禁用，FrameGraph 自动裁掉了这 4 个 Pass 以及它们独占的 3 张中间纹理，显存占用直接降了约 22%。这种优化在手写模式下几乎不可能自动做到。

3.4 三者的咬合关系

用一张表把三者的职责理清楚：

这个分工的核心逻辑是：用户负责"做什么"，FrameGraph 负责"什么时候做、用什么做、要不要做"。职责边界清晰，出问题时也容易定位。

4. 用 ZenFG 搭一条真实管线：从 G-Buffer 到后处理

4.1 场景设定与资源规划

假设我们要搭一条经典的延迟渲染管线，包含这些阶段：

1. 阴影贴图生成
2. G-Buffer 写入（albedo、normal、depth）
3. 延迟光照
4. Bloom 后处理
5. 色调映射与最终合成

先规划资源。这里有个经验：尽量用虚拟资源，只在必须和外部交互时才用外部资源。比如最终输出到 canvas 的纹理是外部资源，中间所有 G-Buffer 附件都是虚拟资源。

const graph = new FrameGraph(device); // 外部资源：最终输出 const swapchain = graph.importResource({ name: 'swapchain', texture: context.getCurrentTexture() }); // 虚拟资源：阴影贴图 const shadowMap = graph.createResource({ name: 'shadowMap', type: 'texture', desc: { size: { width: 2048, height: 2048 }, format: 'depth32float', usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING } }); // 虚拟资源：G-Buffer 三件套 const gbufferAlbedo = graph.createResource({ name: 'gbufferAlbedo', type: 'texture', desc: { size: { width: 1920, height: 1080 }, format: 'rgba8unorm', usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING } }); // ... normal、depth 类似

4.2 阴影 Pass 的声明与实现

阴影 Pass 的特点是：它写shadowMap，但不读任何 G-Buffer 资源。它的输入是场景的几何数据（通过 Uniform 或 Storage Buffer 传入）。

graph.addPass({ name: 'shadowPass', reads: [], writes: [shadowMap], execute: (encoder, res) => { const pass = encoder.beginRenderPass({ colorAttachments: [], depthStencilAttachment: { view: res.shadowMap.createView(), depthLoadOp: 'clear', depthStoreOp: 'store', depthClearValue: 1.0 } }); pass.setPipeline(shadowPipeline); pass.setBindGroup(0, shadowBindGroup); pass.setVertexBuffer(0, meshVertexBuffer); pass.setIndexBuffer(meshIndexBuffer, 'uint32'); pass.drawIndexed(indexCount); pass.end(); } });

这里有个细节值得说：阴影 Pass 的reads是空数组，但这不代表它不依赖任何东西。它依赖的是外部传入的几何数据，这些数据通过 bind group 绑定，不属于 FrameGraph 管理的资源。FrameGraph 只关心它管理的资源之间的依赖。

4.3 G-Buffer Pass 与资源复用

G-Buffer Pass 写三张纹理。这里 FrameGraph 的内存复用开始发挥作用：如果gbufferAlbedo在光照 Pass 之后就不再被读取，那么它占用的显存可以在 Bloom 阶段被复用给别的资源。

graph.addPass({ name: 'gbufferPass', reads: [], writes: [gbufferAlbedo, gbufferNormal, gbufferDepth], execute: (encoder, res) => { const pass = encoder.beginRenderPass({ colorAttachments: [ { view: res.gbufferAlbedo.createView(), loadOp: 'clear', storeOp: 'store', clearValue: { r: 0, g: 0, b: 0, a: 1 } }, { view: res.gbufferNormal.createView(), loadOp: 'clear', storeOp: 'store', clearValue: { r: 0.5, g: 0.5, b: 1, a: 1 } } ], depthStencilAttachment: { view: res.gbufferDepth.createView(), depthLoadOp: 'clear', depthStoreOp: 'store', depthClearValue: 1.0 } }); // ... 绘制场景 pass.end(); } });

注意：G-Buffer 的 normal 纹理用rgba8unorm存储时，需要自己做编码解码（把 [-1,1] 映射到 [0,1]）。如果精度要求高，换成rgba16float，但显存占用翻倍。这个取舍在移动端尤其重要。

4.4 光照 Pass 与依赖自动推导

光照 Pass 读 G-Buffer 和阴影贴图，写 HDR 目标。注意这里我没有指定它在 gbufferPass 之后，FrameGraph 会自动推导。

const hdrTarget = graph.createResource({ name: 'hdrTarget', type: 'texture', desc: { size: { width: 1920, height: 1080 }, format: 'rgba16float', usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING } }); graph.addPass({ name: 'lightingPass', reads: [gbufferAlbedo, gbufferNormal, gbufferDepth, shadowMap], writes: [hdrTarget], execute: (encoder, res) => { const pass = encoder.beginRenderPass({ colorAttachments: [{ view: res.hdrTarget.createView(), loadOp: 'clear', storeOp: 'store', clearValue: { r: 0, g: 0, b: 0, a: 1 } }] }); pass.setPipeline(lightingPipeline); pass.setBindGroup(0, createLightingBindGroup(res)); pass.draw(3); // 全屏三角形 pass.end(); } });

4.5 Bloom 链与多 Pass 组合

Bloom 通常需要多个 Pass：亮度提取、多次降采样模糊、上采样合成。用 ZenFG 组织时，每个 Pass 独立声明，资源依赖自动串起来。

// 亮度提取 const brightTarget = graph.createResource({ ... }); graph.addPass({ name: 'brightPass', reads: [hdrTarget], writes: [brightTarget], execute: (encoder, res) => { /* ... */ } }); // 降采样模糊（可以循环生成多级） const blurLevels = []; for (let i = 0; i < 5; i++) { const level = graph.createResource({ name: `blurLevel${i}`, type: 'texture', desc: { size: { width: 960 >> i, height: 540 >> i }, format: 'rgba16float', usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING } }); blurLevels.push(level); graph.addPass({ name: `blurPass${i}`, reads: [i === 0 ? brightTarget : blurLevels[i - 1]], writes: [level], execute: (encoder, res) => { /* ... */ } }); }

这种循环生成 Pass 的写法，在手写模式下会非常啰嗦，但在 FrameGraph 里就是自然的循环。

4.6 编译与执行：看 FrameGraph 做了什么

const compiled = graph.compile({ outputs: [swapchain] }); // 可以打印编译结果，看看 Pass 顺序和资源分配 console.log(compiled.passOrder); // Pass 执行顺序 console.log(compiled.resourceAlloc); // 资源分配情况 console.log(compiled.culledPasses); // 被裁掉的 Pass const encoder = device.createCommandEncoder(); compiled.execute(encoder); device.queue.submit([encoder.finish()]);

我强烈建议在开发阶段把compiled.passOrder和compiled.resourceAlloc打出来看。有一次我发现某个 Pass 的执行顺序和我预期的不一样，查了半天才发现是我在reads里漏写了一个资源，导致 FrameGraph 认为它不依赖那个 Pass。这种问题在编译结果里一目了然。

5. 实测中踩过的坑：那些文档不会告诉你的细节

5.1 资源依赖漏写导致的"幽灵顺序"

最常见的坑：Pass 实际读了某个资源，但reads里没写。FrameGraph 不知道这个依赖，就可能把 Pass 排到错误的位置。

我遇到过一次：一个后处理 Pass 通过 bind group 读了一张中间纹理，但我忘了在reads里声明。结果 FrameGraph 把它排到了生产者 Pass 之前，运行时读到的是上一帧的旧数据。画面看起来"差不多对"，但偶尔会闪一下。这种 bug 极难定位，因为不报错、不崩溃，只是偶尔画面不对。

经验：养成习惯，每次写execute时，先列出它用到的所有 FrameGraph 管理的资源，然后逐一对照reads和writes。宁可多写，不可漏写。

5.2 资源格式与 usage 的隐性约束

WebGPU 对纹理的usage有严格约束。比如你想把一张纹理同时用作RENDER_ATTACHMENT和TEXTURE_BINDING，声明时必须两个都写上。如果只写了前者，运行时绑定为纹理时会报错。

更隐蔽的是格式兼容性。某些格式不支持作为STORAGE_BINDING，某些格式的TEXTURE_BINDING需要特定的 sample type。这些约束在 FrameGraph 层面不会帮你检查，因为 FrameGraph 只管依赖关系，不管 WebGPU 的格式规则。

经验：在createResource时就把usage写全，别等到运行时才发现不够用。另外，如果某个格式在目标平台上不支持，最好在编译阶段就报错，而不是等到执行时。

5.3 内存复用带来的"数据残留"

FrameGraph 的内存复用是个双刃剑。当它把资源 A 的显存复用给资源 B 时，B 可能会读到 A 的残留数据。如果你的 Pass 用loadOp: 'load'而不是'clear'，就会出问题。

我踩过一次：一个中间纹理被复用后，某个 Pass 用了loadOp: 'load'，结果画面边缘出现了上一帧的残影。查了很久才意识到是内存复用导致的。

经验：对于复用可能性高的中间资源，一律用loadOp: 'clear'。如果确实需要load，确保这个资源不会被复用，或者在 Pass 里显式清空。

5.4 编译开销与每帧重建的取舍

FrameGraph 的编译不是免费的。拓扑排序、依赖分析、内存分配都需要 CPU 时间。如果每帧都重建整个 graph，在复杂管线下可能吃掉几毫秒。

我的做法是：把 graph 的声明和编译结果缓存起来，只在管线结构变化时重新编译。比如调试开关切换、分辨率变化、材质变体切换时才重建。日常渲染直接复用编译结果。

let compiledGraph = null; let lastConfigHash = ''; function getCompiledGraph(config) { const hash = JSON.stringify(config); if (hash !== lastConfigHash) { const graph = buildGraph(config); compiledGraph = graph.compile({ outputs: [swapchain] }); lastConfigHash = hash; } return compiledGraph; }

这个缓存策略在我实测中把每帧的 FrameGraph 开销从约 2.3ms 降到了接近 0。

5.5 调试可视化：把 FrameGraph 画出来

ZenFG 最好用的功能之一是能把编译后的图导出成可视化的依赖图。虽然不能用 mermaid（这里只是描述），但可以导出成 DOT 格式或者简单的文本树。

console.log(compiled.toDot()); // 输出类似： // digraph FrameGraph { // shadowPass -> lightingPass [label="shadowMap"]; // gbufferPass -> lightingPass [label="gbufferAlbedo"]; // ... // }

这个可视化在排查依赖问题时非常有用。我经常在怀疑顺序不对时先导出图看一眼，比读代码快得多。

6. ZenFG 与其他方案的对比：什么时候该用它，什么时候不该

6.1 和直接用 wgpu 比

直接用 wgpu 写管线，自由度最高，但所有资源管理和 Pass 编排都要自己来。适合管线简单（少于 5 个 Pass）或者对性能有极致要求的场景。

ZenFG 适合管线复杂、需要频繁调整 Pass 结构的场景。它的抽象开销很小，但带来的可维护性提升很大。

6.2 和完整渲染引擎比

Three.js、Babylon.js 这类引擎提供了完整的渲染功能，但 FrameGraph 是内置且封闭的。你想改它的 Pass 顺序，得改引擎源码或者用它的扩展机制。

ZenFG 反过来：它只提供 FrameGraph 这一层，渲染逻辑完全由你写。适合那些"我想要引擎的 FrameGraph，但不想要引擎的其他部分"的开发者。

6.3 选型对照表

6.4 一个容易被忽略的点：Compute Pass 也能用

ZenFG 的 Pass 不限于渲染 Pass。Compute Pass 同样可以声明读写资源，纳入 FrameGraph 管理。这意味着你可以把 GPU 计算任务（比如粒子模拟、后处理中的模糊、甚至一些通用计算）也组织进同一张图里。

graph.addPass({ name: 'particleSimPass', reads: [particleBuffer], writes: [particleBuffer], execute: (encoder, res) => { const pass = encoder.beginComputePass(); pass.setPipeline(particleSimPipeline); pass.setBindGroup(0, createParticleBindGroup(res)); pass.dispatchWorkgroups(Math.ceil(particleCount / 64)); pass.end(); } });

注意这里reads和writes是同一个资源——这是合法的，表示"读改写"。FrameGraph 会正确处理这种依赖。

7. 我个人的使用体会与几个实用建议

用了几个月 ZenFG，最大的感受是：它把"渲染管线"从一个"代码结构问题"变成了一个"数据依赖问题"。以前我思考的是"这个 Pass 放在哪一行"，现在我思考的是"这个 Pass 需要什么、产出什么"。思维方式的转变，带来的可维护性提升是实打实的。

几个具体建议：

第一，从第一天就用虚拟资源。不要图省事直接device.createTexture然后importResource。虚拟资源让 FrameGraph 有优化空间，而且资源生命周期自动管理，少写很多destroy()。

第二，把 Pass 的execute写成纯函数。只依赖传入的encoder和resources，不要在里面访问外部可变状态。这样 Pass 可以独立测试，也更容易复用。

第三，编译结果一定要缓存。除非你的管线每帧都在变，否则没必要每帧重新编译。缓存策略上面给过了，直接抄。

第四，调试阶段打开裁剪日志。看看哪些 Pass 被裁掉了，确认是不是你预期的。有时候你以为某个 Pass 在跑，其实它因为没贡献到最终输出被裁了。

第五，资源命名要有意义。texture1、texture2这种命名在调试时是灾难。用gbufferAlbedo、bloomLevel3这种一看就懂的名字，导出依赖图时一目了然。

最后说一个我最近在尝试的扩展方向：把 FrameGraph 的编译结果序列化，做成"管线预设"。这样不同的画质档位（低、中、高、极致）可以预先编译好，运行时直接切换，连编译开销都省了。这个思路在移动端尤其有价值，因为移动端的 CPU 编译开销相对更敏感。