pypdf 的 PDF 版本支持全解析：从 1.0 到 2.0 的特性兼容与版本头处理

pypdf 的 PDF 版本支持全解析：从 1.0 到 2.0 的特性兼容与版本头处理

【免费下载链接】pypdfA pure-python PDF library capable of splitting, merging, cropping, and transforming the pages of PDF files项目地址: https://gitcode.com/GitHub_Trending/py/pypdf

本文以 pypdf 官方文档 docs/user/pdf-version-support.md 为主线，系统梳理 PDF 各版本（1.0 ~ 2.0）的演进脉络、pypdf 对各版本特性的实际支持情况，并结合 pypdf/_reader.py 与 pypdf/_writer.py 的源码实现，讲清"版本头（pdf_header）如何被读取、校验与自动升级"这一底层机制。读完本文，你将能准确判断手中 PDF 文件的版本、预期 pypdf 对特定特性的处理结果，并在写出 PDF 时理解输出文件版本头为何会发生变化。

PDF 版本演进：格式不变，特性递增

PDF 自 1993 年诞生以来，文件的基本结构（对象、交叉引用表、页面树、内容流等）从未改变，每一代新版本只是在既有骨架上新增特性。pypdf 文档给出了完整的时间线：

理解这一演进规律非常重要："文件版本"与"特性支持"是两个层面。一个 PDF 1.4 文件可能不含任何 1.4 新增特性，而一个 PDF 2.0 文件也可能只用了 1.3 时代就有的基础对象。pypdf 官方明确表示：由于格式骨架未变，pypdf 可以正常执行大多数针对 PDF 2.0 文件的操作（拆分、合并、裁剪、变换、文本提取等），即使它并未完整实现 PDF 2.0 的全部新特性。

特性支持矩阵：哪些特性可用，哪些存疑

pypdf 文档以表格形式给出了核心特性与版本、支持情况的对应关系：

其中需要特别留意的是OCG（可选内容组）：pypdf 将其标记为❓，表示支持状态不确定或不完整，使用前应结合实际文件验证。而 CMaps 与透明图形虽分别随 1.4 引入，pypdf 对它们的处理分别落实在 pypdf/_cmap.py（CMap 解析）与文本/页面渲染相关模块中；交叉引用流与对象流则由 pypdf/_reader.py 的交叉引用解析与对象读取逻辑覆盖。

文档特别强调两点：

1. 该表格并不完整——它只列出最常被问到的特性。如果某个特性不在表中，正确的做法是查阅 API 文档、检索 issue 区，或直接用一个包含该特性的真实 PDF 文件实测。
2. pypdf 对缺失特性保持开放态度——如果某特性尚无实现，欢迎先在 issue 区搜索确认是否已存在对应 issue；若不存在则新建 issue 提出需求（项目依赖外部贡献者推动实现）。

从源码结构看，版本头合并逻辑（见下文）只覆盖 1.3 ~ 2.0，这也与实践中 1.0 ~ 1.2 文件已极为罕见、且其特性早已被后续版本完全包含的事实相符。

源码视角（一）：版本头如何被读取与校验

PDF 文件的前 8 个字节即"版本头"，形如%PDF-1.6。PdfReader.pdf_header属性会读取文件开头的 8 个字节并解码返回（见 pypdf/_reader.py 中pdf_header属性定义，约 L305-L317）：

@property def pdf_header(self) -> str: """ The first 8 bytes of the file. This is typically something like ``'%PDF-1.6'`` and can be used to detect if the file is actually a PDF file and which version it is. """ loc = self.stream.tell() self.stream.seek(0, 0) pdf_file_version = self.stream.read(8).decode("utf-8", "backslashreplace") self.stream.seek(loc, 0) # return to where it was ...

配套的单元测试也验证了这一行为：在 tests/test_reader.py 的test_header中，attachment.pdf与crazyones.pdf均被断言读取到%PDF-1.5版本头。

而在解析入口处，pypdf 会先做"基础校验"（见 pypdf/_reader.py 的_basic_validation，约 L746-L762）：读取前 5 个字节，若文件为空则抛出EmptyFileError；若前 5 字节不是%PDF-，则在严格模式（strict=True）下抛出PdfReadError，否则仅记录一条 warning 并继续尝试解析。这意味着：

• 读取 PDF 时，版本头是文件合法性的第一道检查；
• 对于头部被破坏或篡改的文件，pypdf 的严格程度可通过strict参数调节；
• %PDF-前缀通过后，版本号本身（如1.5、2.0）并不会阻止解析——再次印证"格式骨架不变、版本只决定新增特性"的设计。

源码视角（二）：写出时版本头如何自动升级

与读取不同，写出（Writer）侧会自动维护版本头。其核心工具函数是 pypdf/_utils.py 中的_get_max_pdf_version_header（约 L137-L153）：

def _get_max_pdf_version_header(header1: str, header2: str) -> str: versions = ( "%PDF-1.3", "%PDF-1.4", "%PDF-1.5", "%PDF-1.6", "%PDF-1.7", "%PDF-2.0", ) pdf_header_indices = [] if header1 in versions: pdf_header_indices.append(versions.index(header1)) if header2 in versions: pdf_header_indices.append(versions.index(header2)) if len(pdf_header_indices) == 0: raise ValueError(f"Neither {header1!r} nor {header2!r} are proper headers") return versions[max(pdf_header_indices)]

该函数在两个候选版本头中取较高者：如果任一候选不在合法版本列表中，则抛出ValueError。这一行为有测试覆盖：见 tests/test_utils.py 的test_get_max_pdf_version_header，它验证了传入b""与b"PDF-1.2"（缺少%前缀、且不在白名单内）时会抛出ValueError。

_get_max_pdf_version_header的调用点位于 pypdf/_writer.py 的add_page逻辑中（约 L537-L539）：当把来自另一个 PDF 的页面克隆进 Writer 时，会用源文件的pdf_header与当前 Writer 的版本头取最大值，作为新的版本头：

if page_org.pdf is not None: other = page_org.pdf.pdf_header self.pdf_header = _get_max_pdf_version_header(self.pdf_header, other)

这一"取大不取小"的策略保证了：只要合并进来的页面可能依赖更高版本特性，输出文件的版本头就不会低于所需的最低版本，避免生成一个"声明版本低于实际使用特性"的不合规文件。

PdfWriter的版本头行为在 tests/test_writer.py 中有三组直接证据：

• test_pdf_header：新建的PdfWriter()默认版本头为%PDF-1.3；从crazyones.pdf（版本头%PDF-1.5）添加页面后，Writer 版本头自动升级为%PDF-1.5；开发者也可直接赋值覆盖，如writer.pdf_header = b"%PDF-1.6"。
• test_pdf_header__keep_initial_header：PdfWriter(clone_from=reader)默认会重置为%PDF-1.3，而传入keep_initial_header=True时则会保留源文件的原始版本头（此处为%PDF-1.5）。

由此可以总结出写出侧的版本头规则：默认取安全下限，合并高版本页面时自动抬升，且提供keep_initial_header开关来保留源版本。如果你需要控制输出 PDF 的目标版本，直接给 Writer 的pdf_header属性赋形如b"%PDF-1.7"/b"%PDF-2.0"的值即可，但需自行确保写入的对象没有使用超出该版本的特性。

尚未覆盖的特性与生态互补方案

文档明确指出，一些特性 pypdf 目前支持不完整，但可以通过其他开源库补齐：

• 增量式更新（incremental update）PDF 的读取/处理：这是一个被高频请求的特性，对应 issue #3304（增量更新是 PDF 规范中允许在文件末尾追加修改而不重写全文的机制，许多编辑器保存时都会产生此类文件）。
• 密码学签名（Cryptographically sign a PDF）：pypdf 不负责签名，建议使用 pyHanko（对应 issue #302）。
• 表格提取（Table Extraction）：pypdf 只做底层解析，表格结构化提取建议使用 camelot-py（对应 issue #231）。

这些需求并非 pypdf 的设计范围，而是通过"核心解析库 + 专业领域库"的分工来解决。

实战建议：如何确认某个版本特性是否可用

综合文档与源码，验证流程可以归纳为三步：

1. 查文档：先对照本文的特性矩阵，或查阅项目 API 文档中对应模块（如 CMaps 见 pypdf/_cmap.py、加密见 pypdf/_encryption.py）是否有相关实现；
2. 查 issue：在 issue 区搜索该特性关键词，确认是否已有支持请求或已知限制（如增量更新对应 #3304）；
3. 实测：用一份包含该特性的真实 PDF 文件跑通你的读写/提取流程，并注意检查输出文件的pdf_header是否符合预期——必要时显式设置 Writer 版本头。

一句话总结：pypdf 对 PDF 版本采取"骨架兼容、特性分级"的策略——1.0 ~ 2.0 的基础读写全部可用，主流增强特性（CMaps、透明、压缩、交叉引用流、对象流、AES 加密）已就绪，少数特性（如 OCG、增量更新）仍在推进中；理解版本头的读取、校验与自动升级机制，能帮你准确预判任何一次读写操作的输出结果。

【免费下载链接】pypdfA pure-python PDF library capable of splitting, merging, cropping, and transforming the pages of PDF files项目地址: https://gitcode.com/GitHub_Trending/py/pypdf