PDF 导出是典型的重型任务：解析 DOM、测量布局、调用 WASM 写字节流，文档稍长就会让主线程忙上几百毫秒甚至更久。dompdf.js 的架构从一开始就为此做了设计——快照在主线程完成，渲染计算交给 Web Worker，Rust/WASM 内核在后台线程写出 PDF 字节，最终以 Blob 形式交回页面。本文从 Worker 管线原理讲起，说明快照、传输、渲染、回传四个阶段各自的职责，再给出在模块 Worker 中封装 dompdf.js 的完整代码示例，包括消息协议、进度反馈与错误处理，最后总结批量导出与生产环境的最佳实践，帮助你写出不卡主线程、可维护、可观测的导出模块。
dompdf.js 的导出流程分为四个阶段：主线程先遍历 DOM，把需要渲染的节点、样式与几何信息记录成一份结构化快照；快照通过结构化克隆交给 Web Worker；Worker 里运行 Rust/WASM 内核完成布局计算并写出 PDF 字节流；最后结果以 Blob 形式回传主线程。四个阶段各司其职，主线程只做最轻的收集工作，最重的计算全部发生在后台线程，页面因此始终保持响应，这是整个库性能体验的根基。
这套设计不是可有可无的优化，而是长文档场景的刚需。上千页的合同、报表在渲染时需要逐页排版、嵌入字体、压缩字节流，纯主线程执行会让用户看到明显的冻结；把渲染搬进 Worker 之后，导出期间用户仍然可以滚动页面、切换标签、继续编辑，体验从卡死等待变成后台进行，产品质感完全不同，用户对导出功能的信任度也随之建立。
对开发者而言，理解这条管线最大的价值在于知道该在哪里介入：需要定制快照内容，就在主线程的收集阶段处理；需要监控进度，就在消息层做埋点；需要并行导出，就管理多个 Worker 实例。管线的阶段划分是固定的，但每一段的边界都清晰，按边界设计自己的代码，集成成本很低，出问题时也能快速定位到具体环节。
浏览器的主线程同时承担着事件处理、布局、绘制与 JavaScript 执行，任何一项耗时过长都会表现为卡顿。WASM 模块的初始化本身就有几十毫秒的开销，再加上字体解析与整文档排版，一次导出轻松超过数百毫秒，这个时长已经足够让用户感知到页面无响应，甚至触发浏览器的页面无响应提示，直接把功能体验拖入负面区间。
把任务移交给 Worker 之后，主线程的帧率不再受导出影响，动画、输入、滚动全部照常运行。对于文档预览与导出并存的页面，用户可以在导出进行时继续编辑内容，这种并行体验在单线程方案里根本无法实现，也是衡量一个导出库是否达到工程级标准的重要指标，很多团队迁移之后的第一感受就是页面终于不卡了。
另一个被低估的好处是稳定性：Worker 里即使发生异常，也只是当前任务失败，不会拖垮整个页面；配合消息层的超时与重试机制，导出任务可以做到失败可恢复、可重试。相比之下，主线程渲染一旦出错，轻则白屏，重则整个应用崩溃，用户只能刷新重来，两种方案的风险等级完全不同，稳定性差异在长期运行中会体现得越来越明显。
把 dompdf.js 的调用封装进模块 Worker 之后，业务代码只需要向 Worker 投递任务、接收结果，导出逻辑与页面逻辑彻底解耦，主线程不再承担任何渲染计算。注意 Worker 脚本使用 type: 'module' 加载，import 语句与 Vite、Webpack 等构建工具都能正确处理，生产构建时 Worker 会被单独打包成独立文件，资源路径由构建工具统一管理，不需要手工维护。
消息协议建议固定为 { jobId, ...payload } 的形态：jobId 用于关联请求与响应，支持并发任务与乱序回包；payload 里携带 HTML 快照与格式参数，保持消息内容最小化。收到 status: 'done' 之后再触发下载或更新界面，收到 status: 'error' 则展示错误信息并记录日志，协议简单但完整覆盖了成功、失败两条路径，扩展新字段也不会破坏既有约定。
Worker 数量与任务粒度需要权衡：单 Worker 串行处理任务最简单，内存占用低，适合大多数场景；需要并行导出多个文档时，可以按 CPU 核数创建少量 Worker，但每个 Worker 都要独立初始化 WASM 实例，内存开销会成倍增长。先测量再决定，不要盲目开满，通常两个 Worker 就能覆盖绝大多数并行需求，再多收益有限、风险上升。
// pdf-worker.js —— 模块 Worker
import { DomPDF } from 'dompdf.js';
self.onmessage = async (event) => {
const { jobId, html, format } = event.data;
try {
const pdf = new DomPDF();
pdf.addPage(html, { format: format || 'A4' });
await pdf.save(`report-${jobId}.pdf`);
self.postMessage({ jobId, status: 'done' });
} catch (error) {
self.postMessage({ jobId, status: 'error', error: String(error) });
}
};
// main.js —— 主线程发起任务
const worker = new Worker(new URL('./pdf-worker.js', import.meta.url), {
type: 'module',
});
worker.postMessage({ jobId: 1, html: reportHtml, format: 'A4' });
worker.onmessage = (event) => {
if (event.data.status === 'done') console.log('PDF 已生成');
if (event.data.status === 'error') console.error(event.data.error);
};快照是主线程与 Worker 之间传输的核心数据，它的体积直接决定传输耗时。传给 Worker 的 HTML 应该保持精简：只包含导出需要的节点，去掉无关的装饰性元素；图片等大对象优先使用 URL 引用而不是内联 data URL，必要时在快照生成阶段就做压缩与裁剪，从源头控制消息体量，传输与解析都会更快。
postMessage 默认做结构化克隆，深拷贝的开销与数据体积成正比。对于一次性任务，直接把 HTML 字符串与参数放在消息里传递最直观；如果需要在多个任务间复用同一份模板，可以把模板拆成公共部分与数据部分，Worker 端缓存公共模板，消息里只传变化的数据，重复导出场景的传输量可以大幅下降。
消息的时序也值得设计：任务开始、进度更新、任务完成、任务失败，每种状态都对应明确的消息类型。主线程侧用 jobId 维护任务状态表，收到完成或失败消息后清理对应状态，避免内存累积；消息里附带时间戳，方便在日志里还原整个导出过程的耗时分布，排查性能问题时能直接看到瓶颈在哪一段。
长文档导出动辄数秒，用户需要看到进度而不是面对静止的画面。在消息协议中加入 progress 类型消息，Worker 在渲染的关键节点向主线程回报进度值，主线程用进度条或百分比文案展示。进度消息要控制频率，例如每完成百分之五回报一次，避免高频 postMessage 反而拖慢渲染本身，进度更新的节奏以秒级一次为宜。
错误处理要覆盖三个层面：任务内部的异常用 try/catch 捕获并回传 error 消息，这是第一道防线；Worker 脚本本身加载失败要用主线程的 error 事件监听，这是第二道防线；任务长时间没有响应要用 setTimeout 超时兜底，这是第三道防线。三层防线配合，任何一环出问题用户都能得到明确反馈，而不是静默失败，生产环境还应该把错误信息上报到监控平台，方便定位线上问题。
WASM 初始化失败是 Worker 场景最常见的坑：浏览器缓存策略、跨域限制或构建配置错误，都可能导致 wasm 文件加载失败。建议在 Worker 内捕获初始化错误并回传明确信息，同时准备降级方案——检测到 Worker 不可用时回退到主线程直接调用 dompdf.js，功能不中断，体验略有下降但可用性有保障，这种降级设计在线上环境价值极大。
批量导出是后台办公系统的常见需求：一次勾选几十份报表，逐份生成 PDF。用 Worker 队列实现时，主线程维护一个待处理列表，逐个投递给 Worker，每完成一个就推进队列并更新界面；失败的任务单独记录，全部结束后汇总报告，用户一次操作、一次等待，体验完整，不需要为每份文档反复点击导出。
内存管理要格外留意：每份快照都是一份完整的 DOM 拷贝，批量场景下积压的快照会迅速吃掉内存。投递前精简快照内容，处理完的任务及时释放引用，图片等大对象用 URL 而非 data URL 传递；观察任务进行中的内存曲线，接近峰值时降低并发度，这是批量导出稳定运行的关键，内存一旦失控，再快的渲染也会被浏览器崩溃拖垮。
最后是部署层面的建议：Worker 文件与 wasm 资源要配置长缓存，跨域部署时确认 CORS 头正确；构建时给 Worker 文件加内容哈希，避免缓存失效导致线上问题。把导出链路纳入监控与告警，对长文档、大并发场景持续观察，性能问题就能在用户投诉之前被发现和处理，导出功能才能真正成为团队放心的基础设施。
下面的按钮用 dompdf.js 在浏览器端实时生成 PDF，无需后端：
这是由 dompdf.js 渲染的示例 PDF 内容。