解决JS批量生成PDF时的内存溢出与性能卡顿

作者:安全边界

时间:2026-11-22

浏览:523

系统排查JavaScript在浏览器端与Node.js端批量生成PDF时发生内存溢出(OOM)与主线程卡顿的根源,并提供并发限流、资源复用、显式释放与线程隔离的完整实战方案。

文章目录

用 JavaScript 批量导出几十上百份 PDF 时,出现页面卡死、标签页崩溃或 Node.js 进程内存溢出,通常不是某一个库本身“写得慢”,而是并发任务同时堆积、中间位图与字体副本未释放、以及重计算长期占用主线程叠加导致的。要把批量生成做稳,核心解法可以概括为四步:把并发数压下来、让共享资源只加载一次、每生成一份就立刻导出并断开内存引用、再把耗时渲染或拼装隔离出主线程。下文分别针对浏览器端与 Node.js 端给出具体排查路径和可直接落地的代码改造方案。

解决JS批量生成PDF时的内存溢出与性能卡顿
图 0:批量生成 PDF 时的内存堆积问题与受控流水线改造对照

一、先定位卡顿与内存溢出的具体表现和根源

动手改代码之前,先分清当前遇到的是“瞬间爆内存”还是“越跑越慢最终崩掉”,两种表现对应的排查优先级不同。

  • 浏览器端常见表现:点击批量导出后页面按钮立刻失去响应,滚动和动画完全卡死;在生成到第十几份或几十份时,浏览器内存面板持续飙升,最终触发标签页崩溃(例如 Chrome 提示页面崩溃或 Out of Memory)。
  • Node.js 端常见表现:接口长时间无响应、单核 CPU 持续 100%,或者运行一段时间后进程直接退出并打印 FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory;使用 Puppeteer / Playwright 时,还可能出现系统物理内存被多个 Chromium 渲染进程吃光而被操作系统强制杀死。

把排查范围缩小到具体代码,这四类问题占了绝大多数场景:

  1. 用 Promise.all 一次拉起全部任务:假设一次要导 80 份 PDF,items.map(item => generatePdf(item)) 会在同一毫秒创建 80 套 DOM、80 个高分辨率 Canvas 或 80 个 PDF 文档实例。垃圾回收器(GC)根本来不及清理,因为所有任务都处于“等待中”,引用全部活着。
  2. 临时画布、DOM 节点或浏览器页面没有断开引用:浏览器里通过 html2canvas 生成临时画布后只移除外层节点,或忘记调用 URL.revokeObjectURL;Node.js 里打开了 page 但在异常分支跳过 page.close(),底层原生位图内存会持续驻留。
  3. 字体与高清大图被反复解码、重复嵌入:中文字体文件体积较大,如果在循环内部为每份 PDF 重新拉取并注册完整字体,或者把几千像素的原始图片直接按 scale: 3 绘入画布,单份文档的像素内存就会翻数倍。
  4. 渲染与二进制压缩全挤在主线程:生成 PDF 涉及布局计算、图片编码(如 PNG/JPEG 压缩)、字体子集化和字节流拼接,这些大多是同步 CPU 密集型操作,一旦连续执行,事件循环就被彻底堵死。
解决JS批量生成PDF时的内存溢出与性能卡顿
图 1:JS 批量生成 PDF 时导致内存溢出与卡顿的四重成因及传导路径

二、先切断同时堆积:用受控并发与让步调度替代全量并发

读者最容易先想到“把 Promise.all 改成 for...of 串行”。这确实能立刻把峰值内存压到接近单份文档的水平,但在几百份任务下耗时可能偏慢,而且如果单次生成后没有让出事件循环,浏览器界面依然会一卡一卡的。更稳妥的做法是使用固定并发上限的队列调度器,并在每份任务结束后留出短暂的调度间隙。

并发数怎么定才有依据?在浏览器端,DOM 排版和 Canvas 绘制大多竞争同一个渲染管线,并发开到 4 以上不仅不会更快,反而会成倍放大位图峰值,建议设为 1(纯串行)或 2。在Node.js 端,如果是纯内存库(如 pdf-lib、PDFKit)搭配多核 worker_threads,或者使用无头浏览器多页面渲染,一般控制在 2 到 4 个并发槽位,且不超过可用 CPU 核心数与可用内存预算。

下面这段通用的调度器代码同时适用于浏览器和 Node.js 18+ 环境。每完成一份任务,它会主动让出一次事件循环(通过 setTimeout(0)),让 UI 渲染帧或垃圾回收有机会执行:

// 通用的受控并发批处理调度器(浏览器 / Node.js 通用)
async function runPdfBatch(tasks, { concurrency = 1, yieldInterval = 1, onProgress } = {}) {
  const total = tasks.length;
  let nextIndex = 0;
  let finished = 0;

  const yieldToEventLoop = () =>
    new Promise((resolve) => setTimeout(resolve, 0));

  async function worker() {
    while (nextIndex < total) {
      const currentIndex = nextIndex++;
      const task = tasks[currentIndex];

      // 关键:每份任务内部自行完成“生成 + 导出/落盘 + 释放”,不要把整份 PDF Buffer 返回并攒在结果数组里
      await task(currentIndex);

      finished++;
      if (typeof onProgress === "function") {
        onProgress(finished, total);
      }

      // 每完成指定份数让出主线程,避免长时间连续占用事件循环
      if (finished % yieldInterval === 0) {
        await yieldToEventLoop();
      }
    }
  }

  const slotCount = Math.min(concurrency, total);
  const workers = Array.from({ length: slotCount }, () => worker());
  await Promise.all(workers);
}
容易忽略的细节:不要让 task() 返回完整的 Blob、Uint8Array 或 Buffer 再用 results.push(...) 存起来。一旦把每份几 MB 的结果全部存进外层数组,并发限流就失去了意义——堆内存还是会在批处理后半段线性上涨。正确的写法是把“写入磁盘 / 触发下载 / 上传分片”也放进单次 task() 内部,完成后立即让局部变量离开作用域。
解决JS批量生成PDF时的内存溢出与性能卡顿
图 2:控制并发与及时释放的五步流水线操作流程

三、浏览器端批量生成:管住画布、图片和主线程

把并发控到 1 之后,为什么有些前端页面生成到第 30 多份时内存还是只升不降?这往往是因为浏览器里很多大对象并不完全受 JS 垃圾回收的“即时感知”控制,比如底层位图缓冲区和 Blob URL。

1. 显式清零 Canvas 并及时回收 ObjectURL

使用 html2canvas 或直接操作 <canvas> 绘制单页内容时,一个 A4 页面在 2 倍缩放下大约是 1588 × 2246 像素,每个像素占 4 字节,单张画布的原生位图就超过 14 MB。如果一份文档有 5 页,就是 70 MB 以上的非堆内存。处理完每一页后,除了把临时 DOM 从页面移除,还要主动把画布尺寸归零:

// 浏览器端:单份 PDF 渲染并清理 Canvas 与临时 DOM 的标准收尾方式
function cleanupRenderArtifacts(containerEl, canvases, objectUrl) {
  for (const canvas of canvases) {
    const ctx = canvas.getContext("2d");
    if (ctx) {
      ctx.clearRect(0, 0, canvas.width, canvas.height);
    }
    // 将宽高设为 0,促使浏览器尽快释放底层位图缓冲区
    canvas.width = 0;
    canvas.height = 0;
  }

  if (containerEl && containerEl.parentNode) {
    containerEl.parentNode.removeChild(containerEl);
  }

  if (objectUrl) {
    // 触发 a.click() 下载后延迟一小段时间再释放,避免部分浏览器尚未开始读取就失效
    setTimeout(() => URL.revokeObjectURL(objectUrl), 1000);
  }
}

2. 别把缩放倍率(scale)和原始大图直接塞进 PDF

很多人为了让导出文字更清晰,习惯把 html2canvas 的 scale 写成 3 或 window.devicePixelRatio(在 Retina 屏下通常是 2 或 3),甚至直接把用户上传的 4000×3000 原图插进去。分辨率翻倍,像素面积变成 4 倍,3 倍就是 9 倍,不仅内存暴涨,连带 canvas.toDataURL("image/png") 的编码耗时也会成倍增加。

  • 调整缩放与图片格式:日常报表和合同把 scale 固定在 1.5 或 2 已足够打印清晰;大面积含照片或渐变图层的页面优先导出 JPEG(如 canvas.toDataURL("image/jpeg", 0.85))而不是无损 PNG,单页数据体积和编码时间会明显下降。
  • 预处理大图:在插入 PDF 之前,先用离屏画布把远超页面显示尺寸的图片按目标区域缩放到合理像素再转码。

3. 中文字体只加载一次,把字节组装放进 Web Worker

如果采用 pdf-lib 或 pdfmake 这类纯 JS 构建 PDF 的方案(不依赖截图转图片),卡顿的主要原因通常是每份文档重复加载字体和字体子集化、压缩运算占用主线程。正确的做法是在批处理启动前拉取一次字体 ArrayBuffer,然后把生成任务放进 Web Worker,利用 Worker 的独立线程跑完二进制组装,再通过 Transferable 零拷贝传回主线程触发下载。

// pdf-worker.js(运行在浏览器 Web Worker 线程)
// 假设通过打包器或 importScripts 引入了 pdf-lib
let cachedFontBytes = null;

self.onmessage = async (event) => {
  const { type, payload } = event.data;

  if (type === "INIT_FONT") {
    // 整个批量周期内只接收并缓存一次字体字节
    cachedFontBytes = payload.fontBytes;
    self.postMessage({ type: "INIT_DONE" });
    return;
  }

  if (type === "BUILD_PDF") {
    const { taskId, title, lines } = payload;
    try {
      const pdfDoc = await PDFLib.PDFDocument.create();
      if (cachedFontBytes) {
        pdfDoc.registerFontkit(fontkit);
      }
      const font = cachedFontBytes
        ? await pdfDoc.embedFont(cachedFontBytes, { subset: true })
        : await pdfDoc.embedFont(PDFLib.StandardFonts.Helvetica);

      const page = pdfDoc.addPage([595.28, 841.89]);
      page.drawText(title, { x: 48, y: 780, size: 18, font });
      lines.forEach((line, idx) => {
        page.drawText(line, { x: 48, y: 740 - idx * 22, size: 12, font });
      });

      const pdfBytes = await pdfDoc.save();
      // 通过 Transferable 移交底层 ArrayBuffer 所有权,避免跨线程复制大内存
      self.postMessage(
        { type: "PDF_READY", taskId, buffer: pdfBytes.buffer },
        [pdfBytes.buffer]
      );
    } catch (err) {
      self.postMessage({ type: "PDF_ERROR", taskId, message: err.message });
    }
  }
};

主线程侧只需要配合上面的 runPdfBatch,串行或低并发地向 Worker 发送每份任务的数据,收到 PDF_READY 后构造 Blob 触发保存并及时 revokeObjectURL:

// main.js(浏览器主线程)
async function exportBatchWithWorker(items, fontUrl) {
  const worker = new Worker(new URL("./pdf-worker.js", import.meta.url));

  const callWorker = (message, transfer = []) =>
    new Promise((resolve, reject) => {
      const handler = (e) => {
        const data = e.data;
        if (data.type === "PDF_ERROR") {
          worker.removeEventListener("message", handler);
          reject(new Error(data.message));
          return;
        }
        if (data.type === "INIT_DONE" || data.type === "PDF_READY") {
          worker.removeEventListener("message", handler);
          resolve(data);
        }
      };
      worker.addEventListener("message", handler);
      worker.postMessage(message, transfer);
    });

  try {
    // 1. 仅下载一次字体并交给 Worker 缓存
    const fontRes = await fetch(fontUrl);
    const fontBytes = await fontRes.arrayBuffer();
    await callWorker({ type: "INIT_FONT", payload: { fontBytes } }, [fontBytes]);

    // 2. 串行交给 Worker 构建并立即触发下载
    await runPdfBatch(
      items.map((item) => async () => {
        const result = await callWorker({
          type: "BUILD_PDF",
          payload: { taskId: item.id, title: item.title, lines: item.lines }
        });

        const blob = new Blob([result.buffer], { type: "application/pdf" });
        const url = URL.createObjectURL(blob);
        const link = document.createElement("a");
        link.href = url;
        link.download = `${item.id}.pdf`;
        link.click();

        setTimeout(() => URL.revokeObjectURL(url), 1000);
      }),
      { concurrency: 1 }
    );
  } finally {
    // 全部结束后销毁 Worker,释放其内部全部缓存
    worker.terminate();
  }
}
注意 Transferable 转移特性:上面初始化字体时把 [fontBytes] 传给了第二个参数,转移之后主线程里的 fontBytes.byteLength 会变成 0,不能再继续读取。另外,在浏览器中连续自动触发几十次 link.click() 下载可能会被浏览器的安全策略拦截“允许下载多个文件”,如果业务允许,单次导出超多份时更推荐把单份上传或改为服务端生成打包流。

四、Node.js 端批量生成:实例复用、定期重启与流式落盘

把批量生成放到 Node.js 后端执行时,常见有两种技术路线:一类是用 Puppeteer / Playwright 启动无头浏览器把 HTML 渲染成 PDF;另一类是用 PDFKit / pdf-lib 直接在 Node 进程内拼装。两者的内存管理重点不同。

1. 无头浏览器方案:复用 Browser、必关 Page、定期重建进程

很多人写 Puppeteer 批处理时,容易踩两个极端:要么每份 PDF 都调用一次 puppeteer.launch()(启动几十次浏览器,瞬间把 CPU 和内存拉满),要么只开一个 browser 和一个 page 跑上千份从不重启(即使每次清空 HTML,Chromium 渲染进程内部缓存的字体、样式表与 GPU 纹理仍会缓慢增长)。

比较稳妥的做法是:一个批次复用同一个 Browser,每份任务创建独立 Page 并在 try ... finally 中强制关闭,同时每处理固定份数(例如 50 份)主动重启一次 Browser。

// batch-puppeteer.js(Node.js 18+ 环境示例)
import fs from "node:fs/promises";
import path from "node:path";
import puppeteer from "puppeteer";

async function generateBatchPdfsWithBrowser(items, outputDir) {
  await fs.mkdir(outputDir, { recursive: true });

  const RESTART_EVERY = 50;
  let browser = null;
  let processedInCurrentBrowser = 0;

  async function ensureBrowser() {
    if (!browser || processedInCurrentBrowser >= RESTART_EVERY) {
      if (browser) {
        await browser.close();
      }
      browser = await puppeteer.launch({
        headless: true,
        args: ["--no-sandbox", "--disable-dev-shm-usage"]
      });
      processedInCurrentBrowser = 0;
    }
    return browser;
  }

  try {
    for (const item of items) {
      const currentBrowser = await ensureBrowser();
      const page = await currentBrowser.newPage();

      try {
        await page.setContent(item.html, { waitUntil: "load" });
        const targetPath = path.join(outputDir, `${item.id}.pdf`);

        // 直接传 path 参数写入磁盘,避免在 Node 堆内存中持有完整 PDF Buffer
        await page.pdf({
          path: targetPath,
          format: "A4",
          printBackground: true
        });
      } finally {
        // 无论成功或抛错,必须关闭当前 Page 释放渲染内存
        await page.close();
        processedInCurrentBrowser++;
      }
    }
  } finally {
    if (browser) {
      await browser.close();
    }
  }
}

上面代码里有两处很关键的细节:第一,启动参数里加上 --disable-dev-shm-usage,能避免在 Docker 容器中因 /dev/shm 默认只有 64MB 导致复杂页面崩溃;第二,page.pdf({ path: targetPath }) 直接落盘,比先拿回 Buffer 再手动 fs.writeFile 少了一次内存拷贝。如果 HTML 里包含大量不需要的外链统计脚本或广告资源,还可以开启 page.setRequestInterception(true) 拦截无关请求,进一步降低单页开销。

2. 纯 Node 库方案:用文件流(Stream)代替先攒完整 Buffer

如果用 PDFKit 生成包含大量表格、图表的长文档,不要把整份文档读进一个 Buffer 数组后再拼接保存,而是直接把文档流 pipe 到可写文件流,等流触发 finish 再进入下一份:

// batch-pdfkit.js(Node.js 流式写入示例)
import fs from "node:fs";
import path from "node:path";
import PDFDocument from "pdfkit";

function writeSinglePdfStream(item, outputPath, fontPath) {
  return new Promise((resolve, reject) => {
    const doc = new PDFDocument({ size: "A4", margin: 48 });
    const stream = fs.createWriteStream(outputPath);

    stream.on("finish", resolve);
    stream.on("error", reject);
    doc.on("error", reject);

    doc.pipe(stream);
    if (fontPath) {
      doc.font(fontPath);
    }
    doc.fontSize(16).text(item.title);
    doc.moveDown().fontSize(12).text(item.content);
    doc.end();
  });
}

当单份需要处理的任务极其庞大、且要求高吞吐时,可以把整批任务拆成每 100 份一组,交给独立的子进程(child_process.fork)去跑。一组跑完后子进程直接退出,V8 堆内存和所有原生 C++ 扩展占用的内存会由操作系统一次性彻底回收,不存在长期驻留泄漏的风险。

解决JS批量生成PDF时的内存溢出与性能卡顿
图 3:浏览器端与 Node.js 端隔离计算及释放内存的对应结构

五、如何验证内存泄漏与卡顿已经真正解决

改造完成后,不要只看“这次刚好没崩溃”就结束,建议按环境各自做一次可观察的内存基线验证。

1. 浏览器端验证方法

  1. 打开 Chrome DevTools 的 Memory 面板,在开始批量导出前点一次垃圾回收图标(Collect garbage)并拍摄一张 Heap snapshot 作为基线。
  2. 运行一批 20~30 份文档导出;完成后再手动点击一次垃圾回收,拍摄第二张快照。
  3. 对比两张快照中的 Detached HTMLDivElement、HTMLCanvasElement 和 ArrayBuffer 数量。如果优化到位,这些对象数量应当回到接近基线水平,不会出现随着导出份数增加而同比例留存的现象。
  4. 再切到 Performance 面板录制 10 秒左右的导出过程:主线程火焰图应当呈现“一小段任务 + 空闲间隙”交替的锯齿形态,而不是一整条持续数秒的红色长任务(Long Task)。

2. Node.js 端验证方法

在任务循环中每隔 10 份打印一次进程内存指标,重点观察 heapUsed(V8 堆使用量)和 rss(进程常驻物理内存,包含 Buffer 与原生扩展开销):

// 在每批任务结束位置记录内存趋势
function logMemoryUsage(stepLabel) {
  const mem = process.memoryUsage();
  const toMB = (bytes) => (bytes / 1024 / 1024).toFixed(1);
  console.log(
    `[${stepLabel}] rss=${toMB(mem.rss)}MB heapUsed=${toMB(mem.heapUsed)}MB external=${toMB(mem.external)}MB`
  );
}
示例输出(说明:以下为理想稳态下的日志示例,用于对照曲线形态)
[第 10 份完成] rss=142.4MB heapUsed=54.8MB external=18.2MB
[第 20 份完成] rss=156.0MB heapUsed=68.1MB external=21.5MB
[第 30 份完成] rss=148.2MB heapUsed=51.3MB external=17.9MB
[第 40 份完成] rss=158.6MB heapUsed=66.4MB external=20.8MB
[第 50 份完成] rss=145.9MB heapUsed=49.7MB external=16.4MB

可以看到健康的曲线呈上下波动的平稳锯齿状,每经历一次 GC 或 Browser 重启就会回落到固定区间附近;如果 rss 或 heapUsed 在连续多个周期后只升不降,说明某个外层集合、事件监听器或浏览器页面句柄依然存在未断开的引用。

解决JS批量生成PDF时的内存溢出与性能卡顿
图 4:JS 批量生成 PDF 的故障症状、改造手段与验证指标对照

六、常见追问与容易踩的坑

常见疑问 关键结论与操作边界
要求把 100 份 PDF 打包成单个 ZIP 下载怎么办? 在浏览器端同时把 100 份几 MB 的 PDF 塞进内存型 ZIP 对象依然很容易触发标签页崩溃。超过二三十份且单份体积较大时,建议改由后端分批落盘后用流式压缩(如 Node 端 archiver 直接 pipe 到响应流)下载;若必须在浏览器完成,务必先压缩图片和字体子集,并把单份生成后产生的中间 Canvas 与临时变量立即置空,仅保留压缩后的紧凑字节流。
已经改成串行生成了,为什么单份生成时页面还是会卡一两秒? 串行只能减少同时占用的内存总量,解决不了“单份任务内部同步计算耗时过长”。如果单份 PDF 包含几十页 DOM 截图或高分辨率图片编码,html2canvas 的遍历测量和 toDataURL 仍会阻塞主线程。此时应降低 scale、把超长文档拆成多段分页绘制并在页间插入 setTimeout(0),或者改用 Web Worker + 纯数据绘制方案。
在 Node.js 里调大 --max-old-space-size 能一劳永逸吗? 不能。调大 V8 堆内存上限只能推迟报错时间,如果代码中存在结果数组只增不减或事件监听泄漏,最终仍会耗尽整机内存;更重要的是,如果使用了 Puppeteer / Playwright,真正吃掉大量内存的往往是无头浏览器渲染进程(系统级内存),调大 Node 的 V8 参数对浏览器子进程毫无作用,必须通过 page.close() 与定期重启 browser 来控制。

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章