拆分 PDF 不丢来源：给每个分卷一张映射表

本文使用合成样本演示处理方法。代码已通过隔离环境中的示例检查；这不代表对所有真实文件或产品效果的保证。处理重要文件前，请保留原件，并按文中的边界与验收项复核。 拆分后的页码为何总是对不上 使用 pypdf 拆分大文件时，最常见的故障不是报错，而是静默丢失上下文。新文件的第 1 页在物理上是源文件的第 45 页，但 PDF 内部没有保留这个关系。当后续需要回填翻译、校对或合并注释时，你面对着一堆从 0 开始编号的分卷，无法确认它们对应原稿的哪个章节。更隐蔽的问题是命名冲突：如果按固定页数切分，多个分卷可能生成相同的默认文件名，导致后生成的文件覆盖先前的成果，且没有任何警告。 解决这个问题的核心不在于拆分动作本身，而在于拆分后立即生成一份“映射清单”。这份清单必须记录每个输出文件的每一页对应源文件的绝对页码索引，以及输出文件的唯一标识。它不是可选的日志，而是拆分流程的强制产出物。没有这张表，拆分出的 PDF 只是视觉上的碎片，失去了作为工程中间产物的可追溯性。 合成示例：正确映射与边界陷阱 为了说明映射表的必要性，我们构造一个合成场景。假设源文件 source.pdf 共 12 页，需按每 5 页拆分为 3 个分卷。 正确输出预期 ：应生成 3 个 PDF 文件及 1 份 JSON 清单。清单中第一个分卷包含源页索引 [0,1,2,3,4]，第二个包含 [5,6,7,8,9]，第三个包含 [10,11]。每个分卷的文件名应包含序号或哈希以避免冲突，如 split_001_pages0-4.pdf 。 典型错误输入与处理 ：若调用方传入 pages_per_split=0 或负数，程序不应崩溃也不应生成空文件，而应抛出明确异常并终止，提示“分页大小必须为正整数”。另一个边界是源文件页数恰好被整除时，最后一个分卷不应为空；若源文件只有 3 页而要求每 5 页拆分，应正常生成一个包含 3 页的分卷，而非报错或跳过。这些边界条件必须在代码中显式处理，不能依赖 pypdf 的默认行为，因为库本身不关心业务层面的完整性约束。 带断言校验的安全拆分实现 以下 Python 示例演示如何在内存中构造映射关系并完成拆分。代码使用 pypdf 库（推荐 >= 3.0），采用官方推荐的 append 方法替代已弃用的 add_page ，以确保对象克隆的安全性。 注意：此示例为逻辑演示，未执行真实文件 I/O；实际使用时需自行准备只读的 input.pdf 样本，并确保输出目录有写权限，严禁对源文件进行原地覆盖操作。 from pypdf import PdfReader, PdfWriter import json def split_with_manifest(reader, pages_per_split): """ 安全拆分PDF并生成映射清单。 :param reader: PdfReader实例（需以'rb'模式打开） :param pages_per_split: 每个分卷的最大页数（正整数） """ if not isinstance(pages_per_split, int) or pages_per_split <= 0: raise ValueError("pages_per_split must be a positive integer") total = len(reader.pages) manifest = [] writers = [] for start in range(0, total, pages_per_split): end = min(start + pages_per_split, total) writer = PdfWriter() # 使用append代替add_page，支持切片语法且自动处理对象克隆 writer.append(reader, pages=(start, end)) page_indices = list(range(start, end)) filename = f"split_{len(writers):03d}_pages{start}-{end-1}.pdf" manifest.append({ "output_file": filename, "source_page_indices": page_indices, "page_count": len(page_indices) }) writers.append((filename, writer)) # 关键验收点：校验映射完备性，防止静默丢页 all_indices = [idx for entry in manifest for idx in entry["source_page_indices"]] assert sorted(all_indices) == list(range(total)), \ "Page index mapping incomplete or duplicated" return writers, manifest # 使用示例（需读者自备只读 input.pdf） # with open("input.pdf", "rb") as f: # reader = PdfReader(f) # outputs, manifest = split_with_manifest(reader, 5) # # for fname, w in outputs: # with open(fname, "wb") as out_f: # w.write(out_f) # # with open("manifest.json", "w", encoding="utf-8") as mf: # json.dump(manifest, mf, indent=2, ensure_ascii=False) 代码末尾的 assert 是关键验收点：它验证映射的完备性。若源文件结构异常导致某些页无法访问，断言会失败，阻止产出残缺结果。这比事后人工核对可靠得多。同时，使用 append(reader, pages=(start, end)) 不仅语法更简洁，还能自动触发 pypdf 的高级克隆机制，避免手动循环 add_page 可能引发的对象引用副作用。 原厂技术细节与人工审查边界 根据 pypdf 官方文档，拆分不仅是页面复制，还需注意两个易被忽略的技术点： 表单字段冲突 ：若源 PDF 含表单，直接拆分可能导致不同分卷中的同名字段互相干扰。官方建议在拆分前调用 reader.add_form_topname("group_name") 为字段添加命名空间前缀，确保各分卷字段独立可访问。 旋转页面处理 ：若源页面带有 /Rotate 属性，直接拆分可能导致下游渲染错位。建议在拆分前遍历页面，对 rotation != 0 的页调用 transfer_rotation_to_content() ，将旋转信息烘焙到内容流中。 这些细节超出了基础拆分逻辑，需在验收清单中明确区分自动化与人工职责： 观察现象 处理决定 是否适用自动化 映射表中源页索引连续且无遗漏 接受该分卷集 是 某分卷页数为0或参数非法 拒绝整批输出，抛出明确异常 是 输出文件名重复 立即终止，重新生成带时间戳或哈希的文件名 是 源PDF含加密或损坏页 记录失败页索引，标记该分卷需人工修复 否 页面旋转角度非0且未预处理 不自动校正，标记待人工检查方向 否 表单字段名跨分卷冲突 暂停拆分，提示用户预处理字段命名 否 此清单强调：pypdf 能忠实复制页面对象，但若源文件本身存在渲染缺陷或元数据混乱，拆分不会修复这些问题。此时自动化流程应停止并移交人工，而非强行产出看似完整实则不可用的文件。 参考与下一步 pypdf 官方合并文档：https://pypdf.readthedocs.io/en/stable/user/merging-pdfs.html 内存样本的运行入口 以下代码接在上面的函数之后运行，仅使用合成数据，不读取客户文件。 from io import BytesIO source = PdfWriter() for _ in range(5): source.add_blank_page(width=200, height=200) out = BytesIO() source.write(out) parts, manifest = split_with_manifest(PdfReader(BytesIO(out.getvalue())), 2) assert [r["page_count"] for r in manifest] == [2, 2, 1] assert [i for r in manifest for i in r["source_page_indices"]] == list(range(5)) assert [len(w.pages) for name, w in parts] == [2, 2, 1] 将这份检查清单用于文档翻译 文件拆合、加密或附件处理属于交付准备，翻译不能替代这些检查。保留原件和处理清单，再评估译稿的页序、链接与内容完整性。 OmniDoc（产品入口） 提供多格式文档翻译入口，官网介绍了 OCR、术语表与双语对照功能。对希望直接从文件开始处理的团队，这是一条值得用实际样本评估的路径。请使用有权上传的脱敏文件，并用本篇的检查项复核结果；这里不声称 OmniDoc 使用了本文的开源库或内部算法，也不以示例代替产品性能测试。 - 1 -