在PDF中嵌入与提取文件附件：LibPDF附件管理实战清单-开发者社区

【免费下载链接】core

A modern PDF library for TypeScript. Parse, modify, and generate PDFs with a clean, intuitive API.

项目地址：https://gitcode.com/gh_mirrors/core587/core

想在 PDF 里“塞”进一个完整文件，或者把别人 PDF 中藏着的附件完整取出来？LibPDF（一个现代化的 TypeScript PDF 库）把这件复杂的事做到了极简：一行代码嵌入文件附件，一行代码提取附件字节。本文将通过一份实用的PDF 附件管理清单，带你快速掌握 PDF 嵌入与提取文件附件的全部核心操作，包括添加、列出、判断、提取和删除，零门槛上手。

📎 为什么要把文件放进 PDF？

PDF 不只是“看”的格式，它天然支持文件附件（Embedded Files）——可以把 JSON、CSV、Excel、压缩包甚至另一个 PDF 完整嵌入文档内部：

典型场景	说明
数据伴生	合同 PDF 附上原始数据表，阅读与数据一步到位
表单留档	提交表单时把填写数据作为附件保留
打包分发	多文件合并进一个 PDF，避免邮件分开发
归档取证	保留附件原始字节，便于后续程序提取审计

在主流 PDF 阅读器（如 Adobe Reader）中，附件通常出现在“视图 → 导航 → 附件”面板，读者可以像下载一样保存它们。

🚀 快速开始：5 分钟跑通嵌入与提取

如需本地体验完整示例，可以先克隆仓库：

git clone https://gitcode.com/gh_mirrors/core587/core

附件功能的核心 API 全部通过pdf实例上的方法暴露，源码位于 src/api/pdf-attachments.ts，底层文件规格（FileSpec）解析在 src/attachments/file-spec.ts。

➕ 如何向 PDF 嵌入文件附件？

嵌入附件只需三步：准备字节 → 调用addAttachment→ 保存文档。

const pdf = PDF.create(); pdf.addPage({ size: "letter" }); const jsonBytes = new TextEncoder().encode(JSON.stringify({ hello: "LibPDF" })); pdf.addAttachment("data.json", jsonBytes, { description: "Sample JSON data file", mimeType: "application/json", }); const savedBytes = await pdf.save();

🔑要点清单：

MIME 类型可自动识别：不传mimeType时，库会根据扩展名自动推断（.json→application/json、.csv→text/csv等，覆盖 25+ 常见格式），映射表见 src/attachments/file-spec.ts。
同名默认报错：如果附件名已存在，addAttachment会抛出异常，必须显式传{ overwrite: true }才会替换——这是防止误覆盖的安全设计。
元信息完整保留：支持description（描述）、createdAt、modifiedAt（创建/修改时间），不传时间则默认取当前时间，定义见 src/attachments/types.ts。

📦 完整可运行示例：examples/08-attachments/add-attachment.ts，它会一次性嵌入 JSON、TXT、CSV 三种附件并打印清单。

📋 如何列出并检查 PDF 中的附件？

getAttachments()返回一个Map<名称, 附件信息>，每条信息包含文件名、大小、MIME 类型、描述与时间戳：

const attachments = pdf.getAttachments(); for (const [name, info] of attachments) { console.log(`${name}: ${info.size} bytes, ${info.mimeType}`); }

只需判断某个附件是否存在，用hasAttachment(name)即可，无需遍历。列出的字段结构定义在AttachmentInfo接口中（src/attachments/types.ts）。

📦 完整示例：examples/08-attachments/list-attachments.ts —— 它会读取仓库自带的测试文件 fixtures/attachments/attachment.pdf，并顺带检查一个内嵌 zip 的 PDF。

📤 如何从 PDF 提取文件附件？

提取同样是一行代码：getAttachment(name)直接返回附件的原始字节（Uint8Array），存盘或转发随意发挥：

const pdf = await PDF.load(bytes); const data = pdf.getAttachment("report.csv"); if (data) { // data 就是完整的 CSV 原始字节 console.log(`Extracted ${data.length} bytes`); }

💡批量提取技巧：遍历getAttachments()的键，逐个调用getAttachment，即可把 PDF 里所有附件一次性“解包”到磁盘。

📦 完整示例：examples/08-attachments/extract-attachment.ts。

🗑️ 如何删除 PDF 中的附件？

removeAttachment(name)删除指定附件；删除后若文档已无任何附件，库会自动清理/EmbeddedFiles目录树，不留垃圾结构。删除不存在的附件会抛出明确错误，方便你在业务里做校验。

📦 完整示例：examples/08-attachments/remove-attachment.ts —— 演示“添加 3 个 → 删除 1 个 → 验证剩余”的完整流程。

✅ 实战避坑清单

#	检查项	说明
1	重名覆盖	重复添加同名附件前，确认是否需要`overwrite: true`，否则会抛异常
2	字节而非文本	`addAttachment`接收`Uint8Array`，文本请先用`TextEncoder`编码
3	先查后取	提取前用`hasAttachment`判断，避免拿到`null`后再判空
4	修改后保存	所有增删操作在内存中进行，必须`await pdf.save()`才会写入文件
5	外部引用附件	库只识别真正内嵌的文件；外部文件引用会被跳过并产生警告，属于预期行为
6	边界测试素材	多格式、空目录树等边界场景可参考 fixtures/attachments/ 下的测试文件

🎯 总结：一张表看懂全部 API

操作	方法	返回值
嵌入附件	`pdf.addAttachment(name, bytes, options?)`	无（同名未覆盖时抛错）
列出附件	`pdf.getAttachments()`	`Map<名称, 附件信息>`
提取附件	`pdf.getAttachment(name)`	`Uint8Array`或`null`
判断存在	`pdf.hasAttachment(name)`	`boolean`
删除附件	`pdf.removeAttachment(name)`	无（不存在时抛错）

这套简洁的 API 背后，是对 PDF 规范 7.11.3 节 FileSpec / EmbeddedFile 结构的完整实现（见 src/attachments/file-spec.ts 与 src/document/name-tree.ts）。从嵌入到提取，LibPDF 让PDF 文件附件管理变得像操作普通文件一样简单——下一份需要携带附件的 PDF，试试吧！