dompdf.js 与多数前端 PDF 库的最大不同，在于它的内核：布局与渲染引擎用 Rust 编写，编译成 WebAssembly 在浏览器中运行。这个选择不是炫技，而是性能与工程的双重考量——Rust 提供无垃圾回收的确定性内存管理与极致性能，WASM 让这段原生级代码能跨平台运行在任何现代浏览器里。理解 WASM 内核的工作原理，能帮助你更好地使用 dompdf.js：知道管线在哪一阶段耗时、内存在哪里增长、为什么生成不阻塞页面。本文从为什么选择 Rust+WASM 讲起，拆解快照、Worker、WASM、Blob 四阶段管线，分析职责边界、线性内存与 Worker 线程机制，最后给出性能特征与调试方法，让开发者对内核心中有数。
浏览器里的 PDF 生成有两个传统方案：纯 JS 逐段拼装 PDF 字节，或调用浏览器打印能力。前者布局能力弱，复杂 CSS 还原度差；后者依赖系统环境，结果不可控。dompdf.js 选择第三条路：用 Rust 实现完整的 DOM 布局与渲染引擎，编译为 WASM 后由浏览器直接执行，布局质量与性能都接近原生。
Rust 的吸引力在于确定性：没有垃圾回收的随机停顿，内存分配与释放完全可控，这对长时间、大批量的文档渲染至关重要；配合所有权与借用检查，渲染引擎的内存安全在编译期就得到保证，几乎不存在野指针与内存泄漏这类 C 系常见问题，稳定性有根基。
WASM 的吸引力在于可移植性与性能：同一份编译产物能在所有主流浏览器中运行，无需为平台分别适配；执行效率接近原生代码，布局计算、路径填充、图片重采样这类计算密集任务都能跑出接近原生的速度，这是纯 JS 方案难以企及的，也是大文档场景的底气所在。
dompdf.js 的渲染分四个阶段。第一阶段是快照：把传入的 HTML 或 DOM 元素序列化成渲染引擎可理解的结构，样式计算与资源引用在此阶段整理。快照是纯 JS 工作，位于主线程，模板复杂度直接决定这一阶段的耗时，模板越大快照越慢。
第二阶段是 Worker：快照数据被序列化并交给 Web Worker，生成过程从主线程移出，页面交互保持流畅；第三阶段是 WASM：Worker 内的 Rust 引擎完成布局、分页、绘制与图片编码，输出 PDF 的二进制内容；第四阶段是 Blob：二进制结果封装成 Blob，通过 save 触发下载或交由业务继续处理，四阶段各司其职。
理解管线顺序有助于定位问题：耗时异常时，先判断是快照慢（模板复杂）、传输慢（数据量大）还是 WASM 慢（布局与渲染重）。四阶段的耗时可以通过生成前后打点分别测量，把时间花在真正的瓶颈上，而不是盲目优化，排查效率会高很多。
四个阶段的数据流是单向的：快照产物交给 Worker，Worker 把渲染指令交给 WASM，WASM 输出 PDF 字节后再封装成 Blob。理解这条数据流，就能明白为什么模板与图片的准备工作必须在主线程完成，也就能合理地安排预加载与等待逻辑，让整个生成流程顺畅衔接。
用 performance.now() 在生成前后打点，可以量化各阶段的耗时，为优化提供依据。下面示例在 addPage 与 save 周围记录时间戳，输出各阶段耗时到控制台；多次运行取平均值，对比不同模板与图片组合，找出真正的性能热点，让优化有数据支撑。
观测脚本本身很简单，但要坚持在真实数据上跑：样例数据与生产数据的复杂度差异巨大，只有用接近真实的内容测出来的数据才有优化参考价值。建议把打点逻辑封装成工具函数，嵌入到生产代码中按需开启，平时零开销、排查时即取即用，成本极低。
除了耗时，还可以观察资源指标：图片解码后的内存、WASM 内存增长、Blob 大小。耗时的分布会随内容变化，定期跑基准并记录，能提前发现性能退化，而不是等用户投诉后才排查。观测习惯本身，就是性能工程最重要的部分。
import { DomPDF } from 'dompdf.js';
const t0 = performance.now();
const pdf = new DomPDF({ format: 'A4', margin: '20mm' });
const t1 = performance.now();
const html = `
<style>body { font-family: 'Source Han Sans SC', sans-serif; }</style>
<h2>性能观测示例</h2>
<p>记录各阶段耗时，定位性能瓶颈。</p>`;
await pdf.addPage(html, { format: 'A4' });
const t2 = performance.now();
pdf.save('perf-demo.pdf');
const t3 = performance.now();
console.log('init:', Math.round(t1 - t0), 'ms');
console.log('addPage:', Math.round(t2 - t1), 'ms');
console.log('save:', Math.round(t3 - t2), 'ms');四阶段管线里，JS 与 WASM 的分工很清晰：JS 负责与浏览器交互——DOM 操作、资源加载、网络请求、Blob 处理；WASM 负责纯计算——样式解析、盒模型布局、文本排版、路径光栅化与 PDF 编码。边界清晰意味着每一侧都可以独立优化，问题也更容易定位。
对使用者而言，这个边界带来一个实际推论：模板中的网络资源（图片、字体）由 JS 侧负责加载就绪，WASM 侧只消费已就绪的数据。因此图片预加载、字体等待这类资源准备工作，始终是 JS 调用方的职责，代码里 await 资源就绪再 addPage 的写法，正是顺着这个边界设计的，不是可有可无的仪式。
数据在边界间传递有成本：快照数据与图片像素要复制进 WASM 线性内存，数据量越大传递成本越高。合理控制传给渲染引擎的数据量（精简 DOM、降采样图片），就是在降低边界的传输开销。这也是很多性能建议背后的共同原理，理解了它，优化方向自然清晰。
WASM 使用线性内存：一段连续的字节数组，由 Rust 引擎自行管理分配与释放，JS 侧通过 WebAssembly.Memory 访问。与 JS 堆不同，线性内存没有 GC 停顿，分配模式可预测；内存增长以页为单位（每页 64KB），引擎需要更多内存时自动扩容，不会像 JS 堆那样频繁触发回收。
Worker 线程让生成过程不阻塞主线程：快照完成后，繁重的布局与渲染在 Worker 内进行，页面滚动、点击保持流畅；浏览器对 Worker 的数量与内存有上限，超大文档若内存吃紧，可以通过分批生成来降低单次峰值，而不是一次性塞入全部内容，稳定性优先。
线程模型还影响错误处理：Worker 内异常会以事件形式抛回主线程，生成失败时要在 Promise 的 catch 中捕获并提示用户；Worker 与主线程的数据传输使用结构化克隆或转移语义，大对象转移后原引用失效，代码中不要继续使用被转移的对象，避免隐蔽 bug 难排查。
WASM 内核的性能特征可以总结为：计算密集任务快，数据搬运有成本，内存增长可预测。实践中对应三条经验：模板尽量精简以减少快照与传输；图片先降采样以减少解码与搬运；大批量文档分批生成以控制内存峰值。三者结合能让 WASM 引擎始终工作在舒适区，性能稳定输出。
调试性能问题建议按三层展开：先用打点定位阶段耗时，再用浏览器开发者工具观察内存与网络，最后针对具体阶段优化。WASM 的执行在开发者工具的性能面板中可见，火焰图能直观显示布局与渲染的耗时分布，比猜测准确得多，也更容易向团队解释问题。
稳定性调试同样重要：复现问题用固定模板与固定数据，记录浏览器版本与环境；WASM 相关异常要保留完整调用栈与控制台信息。把复现路径沉淀为回归用例，每次内核或依赖升级后跑一遍，性能与稳定性退化都能第一时间被发现，长期维护成本反而更低。
下面的按钮用 dompdf.js 在浏览器端实时生成 PDF，无需后端：
这是由 dompdf.js 渲染的示例 PDF 内容。