Skip to content

Latest commit

 

History

History
172 lines (131 loc) · 9.39 KB

README.zh.md

File metadata and controls

172 lines (131 loc) · 9.39 KB

pdf-lib-plus

pdf-lib-plus: 社区维护分支 TypeScript: 3.9 MIT: 许可不变 tests: 674 docs: 中文 / EN

npm: v1.19.0 CI License Stars Last commit tests: 674 passed since: upstream 2022 PRs welcome

pdf-lib-plus · 中文说明

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 为准。

这是什么

一个用 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-plus
import { 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 原有的行为,本分支未改。

1.18.3 新增:文本提取与删除

本分支在不改原有 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。

1.18.4 修复:表单删除与长生命周期内存

本版继续不改公开 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 本分支 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 私密漏洞报告),高危问题优先排期。