LlosLab Software Development Blog面向 PDF、Delphi 和文档软件开发者的工程笔记

技术文章

在 Delphi 中处理 Office 混合引用 PDF

PDF Programming

从 Microsoft Word、Excel 导出为 PDF 的文件，大多数是混合引用文件。它同时包含两套交叉引用：一套传统定长表供老读取器使用，另一套压缩后的交叉引用流供现代解析器使用，关键桥接点是 trailer 中的 /XRefStm，是否识别它决定你是否读取了完整文档

本文从消费端角度解释 hybrid 文件：文件尾部字节结构是什么、两套索引如何在编辑后不一致，以及 Delphi 管道如何先做分类路由。如何真正合并两套视图在 HotPDF 混合引用文章有完整说明，本篇聚焦在检测布局本身

为什么 Office 同时写两套索引

PDF 1.5 引入交叉引用流和对象流后，结构改造带来体积优势，但老版本读取器无法解释 xref 关键字和传统 trailer 字典消失的文件。ISO 32000-1 的妥协是把两套都写上：传统表覆盖基础对象，流保存全部对象索引，传统尾部会保留 /XRefStm 指向流的偏移，老读者不看这个键，现代读取器则按其扩展完整对象集合

第二层含义是对象可见性。传统表保留 xref 和 trailer，并且把很多对象标成 free，因为它们其实在对象流里；trailer 再带一个 /XRefStm 键，告诉读取器去读完整流视图。老读者不会走这个键，但支持流视图的读取器会同时消费两层索引，所以同一文件既能被 PDF 1.4 阅读器打开，也能被现代解析器完整解读

看一眼文件尾部

示例更容易说明问题。下面是一个小型混合文件尾部（偏移已缩短），Office 文件中 /XRefStm 通常接近文件末尾，查找顺序遵循 PDF 文件结构概览：先找 %%EOF，再读 startxref，再跳到传统表

% ... body objects, including object streams and, at byte 116,
% the cross-reference stream (a stream object with /Type /XRef) ...

xref                    % classic section: what startxref points at
0 4
0000000000 65535 f      % slot 0: head of the free list, always present
0000000017 00000 n      % object 1: the catalog, visible to any reader
0000000000 65535 f      % object 2: marked free -- lives in an object stream
0000000000 65535 f      % object 3: same; only the stream view locates it
trailer
<<
  /Size 4
  /Root 1 0 R
  /XRefStm 116          % byte offset of the cross-reference stream
>>
startxref
7164                    % byte offset of the 'xref' keyword above
%%EOF

这里有两个关键点。第一，startxref 指向的是传统区，因为老读取器只能落在这一入口；交叉引用流地址只在 trailer 的 /XRefStm 声明。忽略这个键就会永远误判文件没有流视图。第二，传统表中把某些对象标成 free，这些对象其实仍在压缩对象流里，故而会出现对象 2 和 3 被标空但流里真实存在。只看传统表会把文档大量对象当不存在

两套视图为什么会偏离

由 Office 导出的原始混合文件通常一致。偏移在后续只更新单一视图的编辑会打破该一致性。比如追加一个增量更新，仅更新 xref 与 trailer 但丢了 /XRefStm，或把旧值原样复制，都会使流视图与传统视图出现“谁对谁错”的差异，更新对象被另一侧当作缺失或陈旧对象

失败表现非常典型：某些注释或表单字段在一个阅读器里存在，在另一个里消失，查找命中的对象也可能偏到不正确的对象。Adobe Acrobat 常常可以静默修复显示，所以问题会在严格的预检、签章、归档流水线里才暴露，通常伴随“Acrobat 打开没问题”误解

真正危险的地方在于 Acrobat 的默认行为。它遇到不一致时通常会重建交叉引用并继续打开，所以损坏者在个人客户端里看起来“没问题”，但同一文件送到更严格的预检器、签名服务或归档入库时才会暴露对象丢失与错位。生产事故里近乎都从这句用户反馈开始

在纯 Delphi 里识别混合文件

识别输入类型不需要完整 PDF 库，/XRefStm 只会出现于传统 trailer，且 trailer 通常在文件后几 KB 内。读取一个限定尾窗并搜索即可完成分类

uses
  System.SysUtils, System.Classes, System.StrUtils, System.Math;

function IsHybridReferencePdf(const FileName: string): Boolean;
const
  TailWindow = 2048;
var
  Stream: TFileStream;
  Buf: TBytes;
  Tail: string;
  Len, TrailerPos, NextPos, KeyPos, StartXrefPos: Integer;
begin
  Result := False;
  Stream := TFileStream.Create(FileName, fmOpenRead or fmShareDenyWrite);
  try
    if Stream.Size < 48 then
      Exit;
    Len := Min(TailWindow, Integer(Stream.Size));
    SetLength(Buf, Len);
    Stream.Position := Stream.Size - Len;
    Stream.ReadBuffer(Buf[0], Len);
  finally
    Stream.Free;
  end;

  // Every keyword involved is 7-bit ASCII, so a byte-wise decode is safe
  Tail := TEncoding.ANSI.GetString(Buf);

  // Find the LAST 'trailer' keyword: with incremental updates,
  // the newest trailer is the one that governs the file
  TrailerPos := 0;
  NextPos := Pos('trailer', Tail);
  while NextPos > 0 do
  begin
    TrailerPos := NextPos;
    NextPos := PosEx('trailer', Tail, NextPos + 1);
  end;
  if TrailerPos = 0 then
    Exit;  // no classic trailer: a pure xref-stream file, not hybrid

  // A hybrid trailer carries /XRefStm between 'trailer' and 'startxref'
  KeyPos := PosEx('/XRefStm', Tail, TrailerPos);
  StartXrefPos := PosEx('startxref', Tail, TrailerPos);
  Result := (KeyPos > 0) and
    ((StartXrefPos = 0) or (KeyPos < StartXrefPos));
end;

该算法返回三种情况。无 hybrid 时 trailer 有但无 /XRefStm；纯 xref 流文件没有 trailer 关键字，只返回 false；只有真正的双索引布局返回 true。生产环境再加两步收口更稳健：解析 /XRefStm 里的偏移并确认该偏移是 stream 且类型是 /XRef，以及将窗口长度参数化，2 KB 够普通 Office 导出但极端 trailer 可以超窗，需要加宽后再判定

更完整的收口方式是把 /XRefStm 后的偏移当作文件内真实地址读取：它对应的对象必须是 stream 且带 /Type /XRef。短文件偶尔把偏移推到 2 KB 外尾窗范围，窗口参数应允许按文件特征扩容

在 Delphi 流程里路由混合文件

识别后是路由策略。只读、渲染或校验场景应走支持合并视图的加载器。PDFium Component 会在加载时解析 /XRefStm 链，后续标准验证可直接使用 对象与 xref-stream 验证文章中的断言体系。解析失败会通过错误码返回，但 PDFium 会尝试修复，因此成功并不代表两视图一致，真正一致性检查应以对象遍历结果对比 trailer 的 /Size 为准

混合文件若因损坏过重无法加载，PDFium 会回报错误，但这个回报不一定能区分是否只是可恢复的结构损坏。错误码里与结构性损坏最相关的是 FPDF_ERR_FORMAT，其余如 FPDF_ERR_UNKNOWN、FPDF_ERR_FILE、FPDF_ERR_PASSWORD、FPDF_ERR_SECURITY、FPDF_ERR_PAGE 也可能出现。关键是，成功加载只说明文件可恢复，不说明两套视图已一致

如果文件会被后续编辑，最安全做法是尽量脱离混合状态。通过 HotPDF 读取再完整保存，可得到单索引文档：不再有 /XRefStm，也不存在双视图漂移。归档入库、严格 RIP 或签章服务前应这样处理；但签名文件要例外，重写会改变签名范围，签名文档应走增量更新而不是重建

混合引用是标准兼容桥不是错误。只要 PDF 1.4 阅读器仍在环境中，Office 会持续输出它。管道若能识别 /XRefStm、用 PDFium Component 做一致性预检，再用 HotPDF Component 归一化到单索引输出，就可以把它当成可控输入