前端 PDF 编辑:pdf-lib 与 pdf.js 的内存边界
在浏览器里给 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 | 修改页面属性并序列化 |
| 图片转 PDF | pdf-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()
执行到这里,内存里同时存在:
sourceBytes:原始文件字节;source:pdf-lib 解析后的对象图;output与copied:复制后的页面对象;bytes:序列化后的完整 PDF;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
No comments yet — be the first to say something