生命周期与事件回调：掌控 dompdf.js 渲染全流程

把一段 HTML 变成 PDF，中间发生了什么？很多开发者只关心 addPage 与 save 的调用，对背后的渲染管线一无所知，遇到长文档卡顿、进度无法反馈、资源加载时序问题时无从下手。dompdf.js 的渲染管线清晰分层：主线程收集 DOM 快照，Worker 线程准备渲染数据，Rust/WASM 内核写入 PDF 字节，最终交给浏览器返回 Blob 或触发下载。理解这条管线，你就能解释为什么导出时页面不卡、为什么长文档要分阶段处理，也能借助官方文档记录的进度回调 onProgress 把渲染过程可视化，提升用户体验。本文按阶段拆解渲染生命周期，讲解进度事件的状态与实用代码，并给出长文档的分阶段渲染策略与常见时序问题排查方法，帮助你从整体上掌控导出过程的每一个环节。同时说明如何用进度事件做性能埋点，让导出流程可观测、可审计。

渲染管线的四个阶段

第一阶段是快照收集：主线程遍历目标 DOM，把结构、样式、图片、字体引用记录成一份独立快照。这一阶段会读取大量节点，模板越复杂耗时越长，而且它发生在主线程，页面可能出现短暂忙碌，这也是建议保持模板精简的原因之一，节点越多快照越慢。

第二阶段在 Worker 线程完成：快照被编码、分页计算与渲染数据准备都在这里进行。由于不占用主线程，UI 可以保持响应，用户看到页面没卡死正是因为重活被移出了主线程，这也是 dompdf.js 相比截图类方案的核心架构优势，长文档导出时体验差异尤其明显。

第三阶段由 Rust/WASM 内核接管：按页面顺序把排版结果写入 PDF 字节流，包括文字字形、图片数据、压缩与页面结构。WASM 的执行效率远高于纯 JavaScript 逐像素处理，长文档的写入速度优势非常明显，输出文件也更小，这是 dompdf.js 高性能的关键所在。

第四阶段是收尾：PDF 字节被封装成 Blob，交由 save 触发下载，或由调用方自行处理。整个生命周期从 addPage 收集内容开始，到 save 完成下载结束，中间各阶段通过进度事件对外暴露状态，供 UI 层消费，理解这条主线，调试与优化就有了方向。

了解四个阶段还有一个实际用途：判断性能瓶颈。导出慢时，先确认是快照收集慢（模板复杂）还是写入慢（内容量大），再针对性优化——前者精简模板，后者拆分内容。方向对了，优化才有效果，盲目调参只会浪费时间。

onProgress 进度回调

官方文档记录了 onProgress 进度回调，用于把渲染过程分阶段暴露给调用方。回调接收一个进度对象，包含 stage 字段与阶段相关数据：例如页面统计阶段会给出总页数，渲染阶段会给出当前页与总页数，UI 层据此渲染进度条或百分比，反馈非常直观。

进度回调的典型价值在长文档：几十页的内容渲染需要数秒，没有反馈用户会以为页面卡死。配合 stage 与当前页、总页数，可以显示正在渲染第 3/20 页这类具体进度，等待体验完全不同，用户对导出耗时的容忍度也会显著提升，减少重复点击与投诉。

注意进度回调只报告渲染进度，不负责错误处理。渲染失败仍然需要调用方通过异常机制捕获；进度事件与错误处理各司其职，组合使用才能构建完整的导出反馈体系，缺一个都会让用户体验出现明显空洞，这一点在架构设计时要提前想清楚。

进度回调也适合做性能埋点：把各阶段耗时记录到日志，长期观察平均值与波动。如果某个版本升级后渲染阶段耗时明显上升，日志会第一时间暴露回归，而不是等用户投诉后才去排查，这是进度事件的隐藏价值，值得认真利用。

完整示例：带进度反馈的导出

import { DomPDF } from 'dompdf.js';

// 类 API 主流程：构造 -> 收集内容 -> 渲染输出
async function exportReport(container) {
  const pdf = new DomPDF({ format: 'A4', margin: '20mm' });
  pdf.addPage(container);

  showProgress(true);          // 渲染开始前显示进度 UI
  try {
    pdf.save('年度报告.pdf');   // 触发渲染与下载
    showProgress(false);
    notifySuccess('导出成功');
  } catch (err) {
    showProgress(false);
    notifyError('导出失败，请重试');
  }
}

// 官方文档记录的 onProgress 进度回调（函数式 API 形态）
// 可用于获取总页数与逐页渲染进度
import dompdf from 'dompdf.js';

const blob = await dompdf(document.querySelector('#capture'), {
  format: 'a4',
  pagination: true,
  onProgress(progress) {
    if (progress.stage === 'countingPages' && progress.totalPages) {
      console.log(`总页数: ${progress.totalPages}`);
    }
    if (progress.stage === 'rendering' && progress.currentPage) {
      console.log(`渲染中: ${progress.currentPage}/${progress.totalPages}`);
    }
  },
});

类 API 流程中的生命周期挂接

使用 new DomPDF() 类 API 时，生命周期同样遵循收集、渲染、输出的顺序，只是入口更简洁：构造实例完成默认配置初始化，addPage 完成内容收集，save 触发渲染并输出。代码层面的事件主要体现为调用顺序与异步边界，按顺序调用即可获得正确结果。

实践中建议把导出流程封装成 async 函数：在 addPage 与 save 前后分别处理 UI 状态——开始前禁用导出按钮并显示加载，结束后恢复并提示完成。异常则通过 try/catch 捕获，把渲染失败与下载失败统一收敛到错误提示逻辑，调用方无需关心内部细节，代码也更整洁。

如果需要更细粒度的阶段信息（页数、渲染进度），可以组合使用官方提供的进度回调与自定义的状态管理：进度回调负责渲染过程的实时反馈，外层 async 流程负责整体的成功与失败语义，两层配合覆盖完整生命周期，代码结构清晰，职责边界分明。

在类 API 流程里，还有一个经常被忽略的时序点：addPage 调用本身不渲染，但内容收集会读取 DOM。如果页面在 addPage 之后、save 之前发生了数据更新或 DOM 变化，渲染结果以 save 时刻的状态为准。理解这一点，就能解释为什么改了数据再导出偶尔出现旧内容。

长文档的分阶段渲染策略

超长文档（几十上百页）一次 addPage 全部塞入，快照收集与分页计算的压力都很大。推荐按章节拆分多次 addPage：每页内容更少，渲染数据更紧凑，进度反馈可以细到章节级别，用户体验与可维护性双赢，是长文档导出的首选组织方式。

拆分后还有一个额外好处：出错时定位范围小。某一章内容导致渲染失败，只需检查对应章节的模板与数据，不需要在整份长文里排查；章节模板也可以独立测试，先单独渲染验证，再拼入完整文档，问题自然更少，交付质量更有保障。

对确实需要单次渲染的超长内容，建议先测量真实耗时：记录 addPage 到 save 完成的时间，观察是否随内容量线性增长。若耗时超出可接受范围，再考虑拆分或提示用户分批导出，避免用户长时间等待后才发现结果异常，体验与稳定性同时兼顾。

分阶段渲染也方便团队协作：每个章节的模板可以由不同成员维护，各自独立测试，最后在汇总函数里按顺序组装。职责边界清晰之后，长文档项目的并行开发效率会明显提升，版本冲突也大幅减少，交付节奏更可控。

时序问题排查清单

最常见的时序问题有三个：图片未加载完就导出导致缺图；动态数据尚未就绪就触发渲染导致内容空白；重复点击导出按钮导致多个渲染任务并发。前两者要求导出前等待资源就绪，第三者建议在导出期间禁用按钮，从源头避免重复触发与任务堆积。

排查渲染结果异常时，先确认输入再怀疑引擎：在浏览器控制台打印传给 addPage 的 HTML 字符串或元素 outerHTML，确认内容完整、样式内联、图片地址有效，再进入渲染环节排查，能快速缩小问题范围，避免在错误层面浪费时间，这是最有效的第一排查动作。

最后，把导出流程的日志留全：开始时间、页数、渲染耗时、失败原因。线上出问题时，这些日志能直接还原现场；配合版本号记录，还能判断问题是否为升级引入，运维与回溯成本都会大幅下降，长期来看是投入产出比极高的习惯。

排查清单的最后一条：善用浏览器开发者工具。在导出前暂停执行、检查 DOM 快照状态，或手动调用渲染函数观察返回值，都能帮助定位时序问题。工具用对了，很多看似玄学的问题其实几分钟就能找到答案，效率完全不一样。