损坏的 PDF 也能打开:hayro 如何自动重建失效的 xref 交叉引用表
损坏的 PDF 也能打开:hayro 如何自动重建失效的 xref 交叉引用表
hayro 是一个纯 Rust 编写的 PDF 解释器与渲染器,它内置了一套完整的 xref 交叉引用表自动重建机制:当 PDF 文件的目录索引损坏、截断或整体缺失时,hayro 会扫描整个文件并手动重建 xref 表,让多数"打不开"的 PDF 依然可以正常解析和渲染。
📖 先搞懂:xref 交叉引用表是什么
PDF 文件由一个个间接对象(indirect object)组成,每个对象都有全局唯一的"编号 + 代数",例如 42 0 obj。对象之间通过 42 0 R 这样的引用互相指向,而页树、根目录、字体、图像全靠这些引用串联。
问题在于:引用只说了"找 42 号对象",却没说"42 号对象在文件的哪个字节位置"。这份**"对象编号 → 文件偏移量"的映射目录**,就是 xref 交叉引用表(xref table)。
PDF 文件结构(简化)
┌────────────────────────────┐
│ %PDF-1.7 │ 文件头
│ 1 0 obj << /Type ... >> │ 对象区
│ 2 0 obj << /Type ... >> │
│ ... 成百上千个对象 ... │
│ xref │ xref 交叉引用表
│ trailer << /Root 1 0 R >> │ trailer 根字典
│ startxref │ startxref 指针
│ 12345 │ → 指向 xref 表偏移
│ %%EOF │
└────────────────────────────┘
正常流程是:从文件尾部找到 startxref 关键字,读取它后面的偏移量,直接跳到 xref 表,再顺着 trailer 里的 /Root 进入整棵对象树。这就是 hayro-syntax/src/xref.rs 中 find_last_xref_pos 做的事。
而 hayro-syntax/src/pdf.rs 的加载入口 new_with_password 体现了整个策略的骨架:先走正常通道,失败了就降级到手动重建。
💥 什么情况下 xref 会"失效"
现实中 xref 失效非常常见,主要有四类:
| 失效类型 | 典型场景 |
|---|---|
| 文件截断 | 下载中断、网盘转存失败,%%EOF 之前的内容丢失 |
| 偏移量错误 | 第三方工具编辑文件后偏移没重算,或文件被追加过数据 |
| 结构缺失 | 文件根本没有 xref 表(某些"假 PDF"、拼接产物) |
| 循环/异常指针 | Prev 指针形成环,或链深超过合理范围 |
任何一项出问题,严格解析器都会直接抛错。hayro 的选择是:不放弃,换一种方式把表重建出来。
🛠️ 核心:hayro 的三级恢复策略
hayro 的修复能力分为三层,层层递进:
第一层 root_xref 正常解析 xref 表 / xref 流(含 Prev 链)
↓ 失败
第二层 fallback 全文件扫描,手动重建 xref 表(加载期兜底)
↓ 加载成功但个别对象仍读不到
第三层 repair() 懒修复:读对象失败时再重建一次并重试(使用期兜底)
第一级:正常解析(快速通道)
xref.rs 中的 root_xref 负责常规路径:
- 支持传统 xref 表(populate_from_xref_table)和 PDF 1.5 引入的 xref 流(populate_from_xref_stream)两种格式;
- 沿 trailer / xref 流的
Prev指针回溯合并多个表段; - 对
Prev链有严格防护:用 visited 集合检测环形引用,并限制链深不超过MAX_XREF_CHAIN_DEPTH(256),见 xref.rs L761-L782。
任何一步返回 None,root_xref 就报错,流程进入第二级。
第二级:fallback 全文件扫描(本文主角)
fallback 函数 会打印一条日志——xref table was invalid, trying to manually build xref table——然后调用 fallback_xref_map_inner 从头到尾逐字节扫描整个文件,规则非常朴素:
扫描三件事
- 找对象头:当前字节是数字?尝试解析
对象编号 代数,再向后探测一个完整合法的对象;只有对象体也解析成功才登记进新表(避免把流数据里的数字误认为对象)。 - 找 trailer:遇到
<<就用探针快速探测字典结构(dict.rs 的 probe_dict),含/Root的候选 trailer 全部收集起来。 - 找对象流:PDF 1.5+ 会把大量字典对象压缩进
ObjStm对象流。扫描到/Type /ObjStm且后面跟stream时,会解码该流并按其内部偏移数组把每个子对象展开登记(xref.rs L134-L167)——这一步对重建现代 PDF 至关重要。
trailer 验证:选出"真根"
扫描可能收集到多个候选 trailer(文件被多次保存时会留下历史 trailer)。hayro 的甄别办法很聪明:对每个候选,解析其 /Root 指向的目录字典,必须包含 /Pages 键才算有效(xref.rs L188-L241)。如果 Root 藏在对象流里,它会穿透对象流去验证。
加密文档的二次重建
第一轮扫描用的是"哑上下文"(没有解密器),加密文档里的对象流读不出来,里面的对象就会全部漏掉。因此一旦候选 trailer 带有 /Encrypt,hayro 会先用初版表建立解密器,再带解密器完整重扫一遍,把对象流里的对象补进表里(xref.rs L247-L263)。
连 trailer 都找不到了?
还有一种更极端的情况:文件尾部整个丢失,一个有效 trailer 都没有。此时 hayro 不会放弃——XRefInput::RootRef 分支会退而求其次,直接用扫描中发现的 Catalog 字典所在对象作为根入口(前提是文档未加密),尽力把 PDF 搭起来。
重建成功后,日志会告诉你成果:rebuild xref table with N entries。
第三级:repair() 懒修复(使用期兜底)
前两级都成功、文档也"打开"了,但个别对象的偏移依然可能是坏的。hayro 为此在读取路径上埋了钩子:
get_with按表定位对象后,发现对象编号对不上或内容不合法,说明这一条表目坏了;- 若表尚未修复过,则调用 repair()——本质是再跑一次全文件扫描、整体替换映射表——然后重试读取(repair_and_get);
- 修复标记
repaired保证重建最多发生一次,避免无限循环;若重试仍失败,则记录错误日志并返回空值,文档其余部分不受影响。
这种"用到才修、只修一次"的设计,让修复成本只在真正需要时付出。
🛡️ 细节防护:重建过程中防什么
重建过程面对的正是"最脏"的输入,hayro 做了不少防御:
- 溢出防护:xref 表的子节头(起始编号 × 条目数)用
checked_add防止恶意构造的99999999999999999999触发跳越(read_xref_table_trailer 有专门的溢出拒绝测试); - 对象流环形检测:对象不能存在于自己所在的对象流中,读取时会检查父链,命中则报
cycle detected in object stream(xref.rs L575-L583); - xref 流字段宽度校验:偏移字段超过 8 字节直接拒绝;
- 偏移单调性校验:对象流内部各成员偏移必须递增,否则按该对象缺失处理。
🧪 效果如何:1400+ PDF 的回归语料背书
这套机制不是纸上谈兵。hayro 的测试语料包含:
- tests/pdfs/custom/ 下 308 个自定义 PDF,覆盖大量畸形文件;
- 从 PDFBox、pdf.js 回归测试套件收集的语料,清单分别记录在 tests/manifest_pdfbox.json 与 tests/manifest_pdfjs.json 中;
- tests/manifest_custom.json 则索引了全部自定义样本。
项目 README 中提到,hayro 能处理其测试套件中的 1400+ 个 PDF——其中相当比例依赖的就是这种"容错加载 + 重建 xref"的能力。
✅ 小结
hayro 打开 PDF 的思路可以概括为一句话:先信目录,目录坏了就重抄一本。
| 层级 | 触发时机 | 对应代码 |
|---|---|---|
| 正常解析 | 每次加载 | root_xref |
| 全文件扫描重建 | root_xref 失败时 |
fallback |
| 懒修复 | 读取个别对象失败时 | repair |
对使用者来说,这一切完全透明:你只是调用了 Pdf::new(data)(可参考 hayro-syntax/examples/iterate.rs 的遍历示例,或 hayro/examples/render.rs 的渲染示例),hayro 已经在后台把损坏的目录悄悄重建好了。这正是它能在真实世界各种"疑难杂症" PDF 上保持高成功率的核心原因之一。