pdf-lib 的社区维护分支 · Community-maintained fork of pdf-lib
公开 API 不变 · MIT 许可不变 · 上游遗留的安全问题,这里真的修了
English / 中英融合主文档 · 📖 本页中文说明 · 文本提取 API · 功能路标 · 本地 playground · 可靠性修复 · 迁移指南 · 更新日志 · 安全政策
本文件是 README.md(英文主文档)的中文导读。
pdf-lib-plus是 pdf-lib 的社区维护分支: 上游自 2022 年起未再发布版本,本分支保持公开 API 与原 MIT 许可完全不变, 先从修复上游遗留的解析/解码安全问题起步。完整 API 文档、示例与贡献者名单 以英文主 README 为准。
- 主文档(英文):README.md
- 更新日志:CHANGELOG.md
- 安全政策与漏洞报告:SECURITY.md
- 贡献指南:CONTRIBUTING.md
- 行为准则:CODE_OF_CONDUCT.md
- 许可证:LICENSE.md(MIT,保留原作者版权声明)
一个用 JavaScript 在任何运行时创建与修改 PDF 文档的库,可在 Node、浏览器、 Deno、React Native 中工作。本分支不改公开 API——原来怎么写,现在还怎么写; 本分支增加的是维护:修复上游报告过、但没有随版本发布的安全问题。
首个版本 1.18.0 修复了以下问题(详见 CHANGELOG):
- PDF 日期解析的正则回溯(ReDoS),改为线性手写解析器并加长度上限;
- JPEG marker 扫描的越界读与死循环,补齐边界检查、尊重
byteOffset/byteLength; - xref 流
/W字段宽度未校验,可能触发异常内存分配,现已先校验再使用; - 解码流缓冲区无上限增长(解压炸弹),已加
maxBufferLength上限。
每项修复都配了对应的回归测试。
npm install @codecloud-dev/pdf-lib-plus
# 或
yarn add @codecloud-dev/pdf-lib-plusimport { PDFDocument, StandardFonts, rgb } from '@codecloud-dev/pdf-lib-plus';
const pdfDoc = await PDFDocument.create();
const timesRomanFont = await pdfDoc.embedFont(StandardFonts.TimesRoman);
const page = pdfDoc.addPage([550, 750]);
page.drawText('你好,PDF', {
x: 50, y: 700, size: 30, font: timesRomanFont, color: rgb(0, 0.15, 0.35),
});
const pdfBytes = await pdfDoc.save();更完整的示例(表单、图片嵌入、合并/拆分、加密文档等)见英文主 README。 中文字符需嵌入支持 CJK 的字体(
@pdf-lib/fontkit+ 自定义字体),标准 14 字体 不含中文字形——这是 pdf-lib 原有的行为,本分支未改。
本分支在不改原有 API 的前提下新增:
extractText(page)/extractTextFromPage(page):提取页面文本;PDFPage#extractText()/PDFPage#extractTextLines():页面实例方法;removeTextContaining(page, substring):按子串删除整段文本显示算子;PDFContentStreamParser:把load()后的压缩内容流解析为算子。
import { PDFDocument, StandardFonts, extractText, removeTextContaining } from '@codecloud-dev/pdf-lib-plus';
const doc = await PDFDocument.create();
const page = doc.addPage([612, 792]);
const font = await doc.embedFont(StandardFonts.Helvetica);
page.drawText('Public content', { x: 50, y: 720, size: 12, font });
page.drawText('SECRET token ABC', { x: 50, y: 700, size: 12, font });
console.log(extractText(page)); // 两行文本
console.log(removeTextContaining(page, 'SECRET')); // 1中文等 CJK 文本需嵌入字体;1.18.3 已真实验证 save → load 后的 Flate
ToUnicode CMap 多字节码解析。完整示例、能力边界与迁移说明见
docs/TEXT_EXTRACTION.md 与 docs/MIGRATION.md。
本版继续不改公开 API,直接修上游公开 issue:
removeField()现在从页面/Annots移除 widget 注解自身的引用,而不是/AP/N外观流引用。删字段后不再有悬空对象,同名字段可以重建, save → reload 后 annotations 全部可解析(上游 #1784 / #1001)。PDFRef/PDFName的 identity 池改为WeakRef+FinalizationRegistry。 活文档仍返回完全相同的实例;文档丢弃后不再被模块级Map永久占住内存 (上游 #1799)。老运行时自动回落到原行为,API 不变。
真实 GC 验证:
yarn build:cjs
node --expose-gc scripts/verify-intern-memory.cjs
# weak intern pool: 1000/1000 dropped PDFName/PDFRef objects collected细节见 docs/RELIABILITY.md。
| 维度 | 上游 pdf-lib |
本分支 pdf-lib-plus |
|---|---|---|
| 公开 API | 原版 | 完全兼容,未改 |
| 许可证 | MIT | MIT(保留原版权声明) |
| 最近发布 | 2022 年后无 | 持续维护安全修复 |
| 目标 | 功能库 | 在保持 API 不变的前提下做安全维护 |
绝大多数代码来自 Andrew Dillon(Hopding)与 pdf-lib 的贡献者,本分支只在
其上做维护。若上游恢复维护,本分支乐于把修复回馈上游。
工具链锁定 TypeScript 3.9,CI 以 yarn install --frozen-lockfile 安装,
依次跑 yarn typecheck、yarn test、yarn build(cjs/es/esm/umd/downlevel-dts)。
package.json 的 resolutions 固定了三个 @types/* 包与 downlevel-dts,
新版类型声明会让 TS 3.9 解析失败——不要单独升它们,详见
CONTRIBUTING.md 与 .github/dependabot.yml 的注释。
yarn install --frozen-lockfile --ignore-scripts
yarn typecheck && yarn test && yarn build请勿在公开 Issue 里贴 PoC。走 SECURITY.md 列出的私密渠道 (匿名票据 / GitHub 私密漏洞报告),高危问题优先排期。