合并 PDF 后目录去哪了：先定义书签保留规则

本文使用合成样本演示处理方法。代码已通过隔离环境中的示例检查；这不代表对所有真实文件或产品效果的保证。处理重要文件前，请保留原件，并按文中的边界与验收项复核。 这篇先解决哪一个问题 合并时先决定是否导入原目录。如果要自行建立顶层入口，应显式 import_outline=False，避免默认导入与手动重建混在一起。这里仅演示页数和目录偏移，不处理表单字段隔离。 自包含的合成示例 依赖见导入列表。代码在内存中构造输入；运行记录单独提供，不代表对所有真实文件的保证。 from io import BytesIO from pypdf import PdfReader, PdfWriter def source(pages): writer = PdfWriter() for _ in range(pages): writer.add_blank_page(width=200, height=200) out = BytesIO() writer.write(out) return out.getvalue() writer = PdfWriter() for title, raw in [("Part A", source(2)), ("Part B", source(1))]: start = len(writer.pages) writer.append(PdfReader(BytesIO(raw)), import_outline=False) writer.add_outline_item(title, start) out = BytesIO() writer.write(out) reader = PdfReader(BytesIO(out.getvalue())) assert len(reader.pages) == 3 assert len(reader.outline) == 2 assert reader.get_destination_page_number(reader.outline[0]) == 0 assert reader.get_destination_page_number(reader.outline[1]) == 2 合并后目录消失的直接原因 使用 PdfWriter.append() 拼接多个 PDF 后，打开输出文件发现左侧导航栏空空如也，或者点击书签跳转到错误页面，这是 pypdf 合并操作中最常见的故障。问题通常不在于“合并”动作本身，而在于源文件的书签（Outline）指向了原始文档的页码或内部对象引用。当多个文档被拼接到一个新文件中时，物理页码发生了偏移，但旧的书签树并未自动更新这些偏移量。更隐蔽的情况是，如果源文件使用了命名目标（Named Destinations）而非绝对页码，且不同源文件存在同名目标，后追加的文件会覆盖先前的定义，导致链接失效。 合成示例：输入边界与预期输出定义 为了验证合并逻辑的健壮性，我们需要构造一套受控的合成样本，而不是依赖生产环境中结构各异的真实文件。假设我们有两个源文件用于测试： 错误/边界输入场景 ：若直接将两个文件 append 而不做任何预处理，最可能的结果是只有一个“user_name”字段可编辑（另一个被遮蔽或数据丢失），且书签可能全部指向 source_a 的页面范围，或者在点击 source_b 对应书签时报错。这种静默失败比程序崩溃更危险，因为它破坏了文档的可用性却不抛出异常。 合并结果的验收标准与人工审查边界 代码执行成功不代表交付物可用。下表列出了针对合并PDF的实际验收观察点，区分了自动化校验与必须人工介入的场景。这些标准适用于任何PDF合并工具的输出验证。 特别注意： reset_translation 方法在重复追加同一 reader 对象时至关重要。如果你需要将同一份PDF的不同页面多次插入到输出中，必须在每次插入前调用此方法，否则第二次插入的将是第一次的引用副本，修改其一会影响另一处。这属于代码演示层面的细节，但在端到端效果验收时，表现为“修改一处内容意外改变了另一处”，极易被误判为软件Bug。 参考资料与下一步行动 pypdf Merging PDFs Documentation pypdf PdfWriter API Reference 具体异常的处理决定 观察 应做什么 不应推断 合并总页数 与各输入相加核对 差异时不交付 第二份目录 检查起始偏移 不能仍指向第一页 源目录保留策略 明确 import_outline 避免重复目录 将这份检查清单用于文档翻译 文件拆合、加密或附件处理属于交付准备，翻译不能替代这些检查。保留原件和处理清单，再评估译稿的页序、链接与内容完整性。 OmniDoc（产品入口） 提供多格式文档翻译入口，官网介绍了 OCR、术语表与双语对照功能。对希望直接从文件开始处理的团队，这是一条值得用实际样本评估的路径。请使用有权上传的脱敏文件，并用本篇的检查项复核结果；这里不声称 OmniDoc 使用了本文的开源库或内部算法，也不以示例代替产品性能测试。 - 1 -