dompdf.js 内存管理与性能调优完整指南

前端 PDF 生成的内存问题，往往在文档变大时集中爆发：页面卡顿、浏览器崩溃、生成失败，根因几乎都是内存峰值失控。DOM 快照、解码后的图片位图、WASM 线性内存、PDF 字节缓冲，每一层都在消耗内存，四层叠加后峰值非常可观。dompdf.js 的 WASM 内核内存管理是确定性的，但调用方的资源使用方式仍然决定最终峰值：图片怎么处理、实例怎么复用、大任务怎么排队，都直接影响内存表现。本文从内存消耗的来源拆解入手，介绍图片位图与 WASM 内存的分工、代码层面的内存控制技巧、批量任务的节流与队列、以及内存监控与调优清单，帮助开发者在内存与性能之间找到平衡，让 PDF 生成在大文档场景下依然稳定可靠。

PDF 生成的内存消耗从哪里来

一次 PDF 生成的内存消耗来自四个层面：DOM 快照与样式数据、图片解码后的位图、WASM 线性内存中的布局与渲染数据、最终 PDF 的字节缓冲。位图通常是最大头：一张 4000×3000 的照片解码后约 48MB，几十张图片就能吃掉数百 MB 内存，是大文档内存压力的主要来源。

四层消耗的叠加方式是峰值的关键：快照、解码、渲染、编码各阶段的高水位并不完全重合，但大图集中解码时峰值会被瞬间推高。理解这一点就能明白，控制峰值的关键不是减少总内存，而是错峰——把大图分批解码、把内容分批渲染，峰值自然下降，体验稳定。

WASM 线性内存按页增长，增长后不会自动收缩：一次高峰渲染后，内存可能长期保持在高水位。对单次导出影响不大，但对高频导出场景，内存回收策略直接影响页面长期稳定性，这也是内存管理值得单独成文的原因，值得每个接入 dompdf.js 的团队认真对待。

图片位图与内存峰值控制

图片位图是内存管理的第一战场。解码一张大图前先问三个问题：显示尺寸多大、显示几次、是否必须原图。显示尺寸决定了位图的下限，降采样到显示尺寸两倍以内，内存立减数倍；同一图片多处使用，解码一次复用即可，避免同一份像素在内存里存多份。

canvas 是降采样的标准工具：drawImage 按目标尺寸绘制，再 toDataURL 导出。降采样要在解码后立即做，不要让大位图在内存中长期驻留；处理完的 Blob 与 URL 及时释放，避免累积。位图的生命周期管理，是内存调优里收益最直接的一环，代码量不大效果明显。

格式选择也影响位图大小：JPEG 解码后的位图与 PNG 相同（都是 RGBA 像素），但源文件小、解码快；体积敏感的文档用 JPEG 源图配合适度压缩，既能控制文件大小，又能减少解码时的临时内存，一举两得，图片处理策略应该与格式选型一起规划。

代码示例：控制内存的生成流程

代码层面的内存控制，核心是让资源生命周期可预期：用完即释放、实例可复用、大对象及时置空。下面示例演示一个内存友好的生成流程：图片先降采样再入模板，生成完成后释放 Blob URL 与图片引用，DomPDF 实例用完后置空引用，帮助浏览器尽快回收，水位平稳。

示例中 createObjectURL 生成的 URL 在保存后通过 revokeObjectURL 释放；大图引用在导出完成后置为 null；WASM 实例随作用域结束自然释放。这些细节单个看微不足道，组合起来能在高频导出场景显著降低内存水位，页面长期运行不卡顿，用户体感差异明显。

还要注意避免闭包与全局引用：模板字符串、图片数据这类大对象不要长期挂在全局或闭包中，用完就释放。内存回收交给浏览器 GC 与 WASM 分配器，但前提是代码不再持有引用。这是开发者唯一需要做、也唯一能做的部分，做好它，内存问题就解决了一大半。

import { DomPDF } from 'dompdf.js';

async function prepareImages(urls) {
  return Promise.all(urls.map(async url => {
    const blob = await (await fetch(url)).blob();
    const img = new Image();
    img.src = URL.createObjectURL(blob);
    await img.decode();
    const canvas = document.createElement('canvas');
    const max = 1200;
    const scale = Math.min(1, max / Math.max(img.naturalWidth, img.naturalHeight));
    canvas.width = Math.round(img.naturalWidth * scale);
    canvas.height = Math.round(img.naturalHeight * scale);
    canvas.getContext('2d').drawImage(img, 0, 0, canvas.width, canvas.height);
    URL.revokeObjectURL(img.src);
    return canvas.toDataURL('image/jpeg', 0.85);
  }));
}

const images = await prepareImages(['images/a.jpg', 'images/b.jpg']);

const html = `
  <style>body { font-family: 'Source Han Sans SC', sans-serif; }</style>
  <h2>内存优化示例</h2>
  <img src="${images[0]}" style='width:100%'>`;

const pdf = new DomPDF({ format: 'A4', margin: '20mm' });
await pdf.addPage(html, { format: 'A4' });
pdf.save('memory-demo.pdf');

WASM 内存与 JS 堆的分工

WASM 线性内存与 JS 堆是两个独立的内存世界：布局、渲染、PDF 编码的数据活在 WASM 侧，DOM、字符串、图片 Blob 活在 JS 侧。两侧之间的数据传递需要复制，复制量越大，瞬时内存越高，这是理解内存峰值的另一把钥匙，也是很多内存问题被忽视的根源。

减少两侧复制量的方法，与性能优化高度重合：精简 DOM 减少快照数据量，降采样图片减少像素搬运量，避免重复传递同一份数据。数据在两侧间每复制一次，峰值就多一份，控制复制次数等于直接控制峰值，两条优化路径殊途同归，可以一起推进。

WASM 内存增长后不自动收缩，是设计使然：引擎宁可保留已分配的内存，也不愿承担反复扩容的成本。对长驻页面，可以定期检查 WebAssembly.Memory 的 buffer 长度与页面内存占用，结合浏览器任务管理器观察趋势，确认是否存在持续增长的内存异常，早发现早处理。

理解分工还有一个实际收益：排查内存问题时，先判断数据活在哪个世界。图片、字符串、DOM 相关的问题查 JS 堆；布局、渲染、编码相关的问题查 WASM 线性内存。按世界分流排查，定位速度明显提升，也避免在错误的工具里寻找不存在的证据。

批量任务的节流与队列

批量导出是内存压力的放大器：几十个导出任务同时进行，峰值内存成倍上升，浏览器可能直接崩溃。队列化是标准解法：任务按顺序执行，前一个完成再启动下一个，瞬时内存被压到单任务的量级，稳定性和可预测性大幅提升，用户排队等待也比集体失败好得多。

队列之外还可以节流：任务之间留出微小的间隔（如 50 到 100 毫秒），让 GC 有机会回收上一轮的临时对象，长队列场景下总耗时增加有限，内存水位却明显下降；对超大文档，还可以拆分为多页分批渲染，进一步错开峰值，双管齐下效果更佳。

实现队列时注意错误隔离：单个任务失败不应阻塞后续任务，记录失败原因并继续处理；任务间共享的资源（如预加载的图片缓存）单独管理，避免队列运行期间资源被意外释放。健壮的队列是批量导出功能上线的底线保障，也是工程成熟度的体现。

队列与节流还要考虑用户感知：任务排队时给出明确的排队位置与预计时间，比静默等待更友好；批量完成后统一汇总成功与失败的结果，让用户一次看清全貌。工程上的稳定性手段，最终都要落到用户体验上，两者兼顾的队列才算是合格的实现。

内存监控与调优清单

调优前先建立监控：浏览器任务管理器与 performance.memory 可以观察页面内存趋势，开发者工具的内存面板可以抓取堆快照对比前后差异；把生成前后的内存变化记录成日志，长期追踪，内存问题就不再是黑盒，出现异常时能快速回溯定位。

调优清单按收益排序：图片降采样与格式统一收益最大且风险最低；DOM 瘦身与快照精简零成本；实例复用与对象释放是代码层面的基本功；队列化与分批渲染解决批量场景的峰值问题。每项改动后观察内存曲线，确认收益真实存在，再进入下一项。

最后把内存纳入发布标准：每次功能上线前跑一遍代表性场景的内存基准，内存峰值超过阈值即告警。内存问题具有累积性，早期发现成本最低，把监控与基准固化到流程里，PDF 生成功能才能长期稳定，而不是每次文档变大就提心吊胆、临时救火。