前端 PDF 编辑:pdf-lib 与 pdf.js 的内存边界

2026-11-19 前端开发 有希 38 views

在浏览器里给 PDF 删页、调序、旋转、加水印,看起来只是改几个数字,实际会同时把源文件、每页缩略图、复制后的页面对象和最终字节放进内存。大文件在手机上失败,往往不是 API 用错,而是峰值内存或字体编码先到了边界。

先给结论

  • 两套库分工不同:pdf.js 负责把页面画成缩略图,pdf-lib 负责复制页面、旋转、加水印和导出;两套对象模型不共享。
  • 源字节要留副本:pdf.js 会把传入的 ArrayBuffer 转交给 worker,之后原缓冲区不可再用。
  • 导出会再复制一遍:copyPages 生成新的页面对象,save 再把整份文档序列化成字节;峰值至少是源文件、解析对象、复制页面、输出字节同时存在。
  • 字体与加密是硬边界:StandardFonts.Helvetica 只能编码 WinAnsi,中文水印会直接抛错;加密 PDF 需要单独处理。

可以直接在 PDF 页面管理工具 里对照下面的流程。

两套库的分工

能力使用的库原因
打开文件、渲染缩略图pdfjs-dist解析 PDF、执行页面内容流、画到 Canvas
复制、删除、排序页面pdf-lib直接操作页面树,不改内容流
旋转、水印、导出pdf-lib修改页面属性并序列化
图片转 PDFpdf-lib + Canvas统一格式、处理透明与 EXIF

pdf.js 的文档对象不能直接交给 pdf-lib。前者面向“渲染”,后者面向“结构”,中间只能通过字节或独立解析转换。理解这一点,后面的副本和内存问题就顺了。

源文件为什么要留副本

打开文件时,页面拿到的 ArrayBuffer 被用了两次:

const buffer = await file.arrayBuffer()
sourceBytes = new Uint8Array(buffer.slice(0))
const pdfjs = await loadPdfjs()
// pdf.js 会接管传入的 buffer,必须给一份新的
const doc = await pdfjs.getDocument({ data: new Uint8Array(buffer.slice(0)) }).promise

源码注释写得很直接:pdf.js 会把 buffer 转交给 worker,转移后原缓冲区长度变成 0,后续 PDFDocument.load(sourceBytes) 就读不到内容。所以这里做了两次 slice(0):一次留给导出,一次给 pdf.js。

这个坑在没有 worker 的退化路径里不一定出现,本地开发很容易漏掉,到了线上开启 worker 才炸。凡是把二进制交给会 postMessage 的库,都要假设它会转移所有权。

缩略图:把峰值压在前端

缩略图按页面尺寸计算缩放,限制最大宽高,并设置上限 2 倍:

const base = page.getViewport({ scale: 1 })
const scale = Math.min(200 / base.width, 260 / base.height, 2)
const viewport = page.getViewport({ scale })
const canvas = document.createElement('canvas')
canvas.width = Math.ceil(viewport.width)
canvas.height = Math.ceil(viewport.height)
// 白底 + 渲染
result.push({
  index: pageNumber - 1,
  thumb: canvas.toDataURL('image/jpeg', 0.7),
  rotation: 0,
  removed: false
})

几个取舍:

  • 200×260 是卡片展示尺寸,超过这个尺寸的像素在列表里看不到;
  • 上限 2 倍避免小页面被放大到模糊;
  • JPEG 质量 0.7 控制 data URL 长度,100 页大约占用几 MB 字符串;
  • 每页都新建 Canvas,渲染完成后 canvas 本身可以被回收,但 data URL 会留在 pages 数组里。

如果 PDF 有 500 页,即使用户只看前几页,当前实现也会一次性渲染全部缩略图。这是内存和等待时间的第一个峰值。更稳的做法是虚拟列表按需渲染,或者先只渲染前 N 页,滚动时再补。工具页选择“一次渲染全部”,换来实现简单、滚动不闪白,但大文件要接受更长的等待。

需要把某页导出成图片时,用 PDF 转图片工具 更直接,它的渲染参数与这里不同,专为高分辨率输出设计。

导出:copyPages 与 save 的副本

导出时重新加载源字节,复制保留下来的页面:

const source = await PDFDocument.load(sourceBytes)
const output = await PDFDocument.create()
const copied = await output.copyPages(
  source,
  kept.map((item) => item.index)
)

copied.forEach((page, position) => {
  page.setRotation(degrees(kept[position]!.rotation))
  output.addPage(page)
})

const bytes = await output.save()

执行到这里,内存里同时存在:

  1. sourceBytes:原始文件字节;
  2. source:pdf-lib 解析后的对象图;
  3. output 与 copied:复制后的页面对象;
  4. bytes:序列化后的完整 PDF;
  5. Blob 与下载链接:浏览器可能再复制一份。

对一个 50MB 的扫描件,峰值很容易超过 150MB;手机浏览器给单页的内存额度更紧。save() 返回的是完整字节,没有流式输出,所以“边复制边写盘”在 pdf-lib 里做不到。

可行的缓解手段:

  • 限制单文件大小与页数,在入口就给出提示;
  • 导出后及时释放 sourceBytes,不要在同一页面反复导出多个大文件;
  • 合并、拆分分批处理,避免一次把所有源文件都读进内存;
  • 对超大文件改用服务端处理,前端只做预览。

旋转用 page.setRotation(degrees(...)) 修改页面属性,不会重绘内容流,成本很低。排序则是 copyPages 的顺序,源页面本身不变。

水印与坐标

水印在导出阶段画到每一页:

const font = await output.embedFont(StandardFonts.Helvetica)
const { width, height } = page.getSize()
const size = Math.max(14, Math.round(width / 18))
page.drawText(text, {
  x: width * 0.12,
  y: height * 0.3,
  size,
  font,
  color: rgb(0.5, 0.5, 0.5),
  opacity: opacity.value,
  rotate: degrees(30)
})

PDF 的坐标原点在左下角,y = height * 0.3 是从底部往上 30% 的位置;字号按页面宽度计算,横版和竖版的观感接近。旋转 30 度形成斜向水印,起点压在左下,避免长文本从右上角溢出。

图片转 PDF 的版式计算是另一套坐标。image-pdf.ts 用 top-based 的布局,写进 PDF 时再做一次换算:

page.drawImage(embedded, {
  x: layout.offsetX,
  y: layout.pageHeight - layout.offsetY - layout.drawHeight,
  width: layout.drawWidth,
  height: layout.drawHeight
})

如果直接把 top-based 的 offsetY 当 PDF 的 y,图片会上下颠倒。图片本身还要先经过 Canvas 重编码,处理 EXIF 方向与透明通道,具体原因见 Canvas 照片方向。

中文水印的硬边界

水印输入框没有限制字符集,但字体用的是:

const font = await output.embedFont(StandardFonts.Helvetica)

Helvetica 是标准 14 字体之一,只能编码 WinAnsi 字符集。输入中文时,drawText 会抛错:

WinAnsi cannot encode "机" (0x673a)

页面捕获异常后显示通用的“处理失败”,用户看不到具体原因。要支持中文水印,需要嵌入包含中文字形的 TTF/OTF,并注册 @pdf-lib/fontkit:

import fontkit from '@pdf-lib/fontkit'
pdfDoc.registerFontkit(fontkit)
const fontBytes = await fetch('/fonts/NotoSansSC-Regular.otf').then(r => r.arrayBuffer())
const font = await pdfDoc.embedFont(fontBytes, { subset: true })

字体文件会增加导出体积,subset: true 只嵌入用到的字形,能压住大部分增长。另一个选择是明确提示“水印仅支持英文与数字”,不要等到导出时才失败。

加密 PDF 与其他边界

pdf-docs.ts 里对加密文档有明确处理:

const doc = await PDFDocument.load(bytes, { ignoreEncryption: true })
if (doc.isEncrypted) {
  throw new Error('PDF_ENCRYPTED')
}

先允许加载,再检查标记,页面可以据此显示“文档已加密”。但 pdf-edit 页面直接 PDFDocument.load(sourceBytes),没有 ignoreEncryption,加密文件会在加载阶段抛错,最终只显示通用失败。两处行为不一致,是后续可以统一的地方。

pdf.js 打开需要密码的 PDF 时会抛 PasswordException,当前页面也没有密码输入流程。带权限密码的文档(能打开但不能编辑)在 pdf-lib 里可能复制失败或丢失权限标记,这类文件应在入口识别并提示,而不是让用户等到导出。

还有一个细节:下载链接创建后立即 revokeObjectURL。多数浏览器在点击后已经接管下载,但部分环境需要延迟回收;更稳的写法是 setTimeout(() => URL.revokeObjectURL(url), 1000)。

验证清单

场景预期
20 页 PDF 打开生成 20 张缩略图,旋转、排序、删除可操作
删除部分页后导出输出页数与保留页一致,顺序按当前列表
中文水印当前实现抛 WinAnsi cannot encode,页面显示失败
英文水印导出成功,水印斜向、半透明
加密 PDF加载失败或提示加密,不进入编辑
图片转 PDF每张图一页,透明图保留透明,照片方向正确
替换文件旧缩略图与源字节被清空,不叠加

FAQ

为什么大 PDF 在手机上会失败?

导出时源字节、解析对象、复制页面和输出字节会同时存在,峰值是文件大小的数倍;移动端单页内存额度更紧。先限制文件大小与页数,再考虑服务端处理。

pdf.js 和 pdf-lib 能共用同一个文档对象吗?

不能。pdf.js 的文档面向渲染,pdf-lib 的文档面向结构,二者没有兼容的页面对象。只能各自解析同一份字节。

中文水印为什么导出失败?

StandardFonts.Helvetica 只支持 WinAnsi 编码,中文字符无法映射,drawText 会直接抛错。需要嵌入中文字体并注册 fontkit。

加密 PDF 能处理吗?

当前页面没有密码输入与权限处理,加密文件会失败。工具函数层能识别 isEncrypted,但编辑页没有接入。

页面旋转是改原文件吗?

不是。旋转只修改导出文档里页面的 Rotation 属性,源文件字节不变;预览里的旋转是 CSS 变换,两者在导出时才合并。

结语

PDF 编辑的代码量不大,难点在边界:谁拥有缓冲区、导出时复制了几份、字体能编码哪些字符、加密文件在哪一步失败。把这些边界写进入口校验和错误提示,比在导出失败后猜原因有效得多。更多前端实现记录在 前端开发 分类下。

Comments

Sign in to join the discussion

No comments yet — be the first to say something

Related Articles