企业官网建设流程全解析

简介：这份资源面向需要处理 PDF 目录结构的 Python 开发者与电子书整理爱好者，聚焦用 PyPDF2 读取现有书签并按 JSON 配置批量写入新书签这一典型场景，属于进阶脚本类实践素材。压缩包共 2 个文件，约 40KB，主体为一份可直接运行的 Python 脚本，另附一个 gz 源码包，便于对照库版本与依赖环境。已有 2519 人学习下载，说明该方案在 PDF 批处理需求中具备一定参考价值。脚本围绕书签层级、标题与目标页码的解析展开，演示了从读取大纲到生成带书签新 PDF 的完整链路，并提示 PyPDF2 不支持原地修改、需另存输出的关键限制，读者可据此快速搭建自己的书签迁移或批量生成工具，减少重复手工操作。

1. 从一份 800 页的扫描版手册说起：PDF 书签批量处理到底解决什么问题

上周帮某实验室整理一批设备手册，800 多页的 PDF，目录页拍得清清楚楚，但侧边栏空空如也——翻到第 47 章想回看某个参数表，只能靠 Ctrl+F 碰运气。这种场景下，python pdf 书签批量处理不是炫技，而是刚需：把散落在正文里的章节标题、页码规律，批量转成可点击的 PDF 大纲（outline/bookmark），一次写入、全篇生效。这份源码包干的就是这件事——读取现有书签做结构分析，按规则批量写入新书签，支持多级嵌套和页码偏移校正。适合手里堆着一批结构相似 PDF、又不想逐页手点书签的从业者，新手照着改参数能跑，熟手能看清它处理加密文档和异常页码时的边界。

2. 选型先立住：为什么是 pypdf 而不是别的库

2.1 三个主流库的能力边界对比

PDF 书签在文件结构里叫 outline，本质是一棵挂载在文档根节点上的树，每个节点带标题、目标页引用和层级关系。能操作它的 Python 库不少，但能力差异很大，选错了后面全是返工。

这份源码选 pypdf，理由很实在：纯 Python 实现，不依赖编译好的二进制，扔到任何一台装了 pip 的机器上都能跑；写书签的 API 直接暴露add_outline_item，层级靠父节点参数控制，逻辑清晰；读的时候能拿到每个书签指向的页对象，做页码偏移校正时不用反查。PyMuPDF 性能更好，但它的书签写入对嵌套层级的容错偏严，页码算错一位就整棵树错位，调试成本反而高。常见做法是：结构分析和批量写入用 pypdf，需要预览渲染再临时调 fitz，两套不冲突。

2.2 书签树在 PDF 里的真实结构

很多人以为书签就是「标题 + 页码」的平铺列表，实际不是。PDF 的 outline 是一棵树，根节点下有若干一级节点，每个一级节点可以挂子节点，子节点还能继续挂。每个节点至少包含三样东西：/Title标题字符串、/Dest或/A指向的目标位置、/Parent和/First/Next等兄弟父子指针。pypdf 把这些封装成了对象，读的时候给你一个嵌套列表，写的时候你按顺序调add_outline_item(title, page_number, parent=...)，它自己维护指针。

理解这一点很关键：批量写入时如果父节点传错，生成的不是「层级乱了」而是「书签点不动」——因为目标页引用断了。源码里专门有一段校验逻辑，写完重新读一遍树深度和目标页有效性，就是防这个。

2.3 环境准备与依赖锁定

依赖就一个，但版本要卡住。pypdf 在 3.x 和 4.x 之间改过 outline 相关的方法签名，老代码直接升会报TypeError。

# 建议锁在 4.x，add_outline_item 的 parent 参数行为稳定 pip install "pypdf>=4.0,<5.0" # 校验安装 python -c "import pypdf; print(pypdf.__version__)"

参数说明：版本上限卡 5.0 是血泪经验，某次不锁版本，CI 上装到新大版本，add_outline_item的parent从接受对象变成接受索引，整批脚本静默写出一堆平铺书签，还没报错。锁版本这一步别省。

3. 读取现有书签：把 outline 树摊平成可分析的数据

3.1 递归遍历拿到完整层级和页码

读书签的核心是把嵌套树摊平，同时保留层级深度和目标页码，后面做规则匹配和偏移校正都靠这份数据。

from pypdf import PdfReader def walk_outline(reader, outline=None, depth=0, parent_title=""): """递归遍历书签树，返回 [(层级, 标题, 页码, 父标题), ...]""" if outline is None: outline = reader.outline result = [] for item in outline: # 嵌套列表代表子节点集合，不是书签本身 if isinstance(item, list): result.extend(walk_outline(reader, item, depth + 1, parent_title)) continue # 目标页可能是页对象，也可能是命名目标，统一转页码 try: page_no = reader.get_destination_page_number(item) except Exception: page_no = -1 # 目标失效，标记出来 result.append((depth, item.title, page_no, parent_title)) parent_title = item.title return result reader = PdfReader("manual.pdf") for depth, title, page_no, parent in walk_outline(reader): print(f"{' ' * depth}{title} -> p{page_no + 1} (父: {parent})")

逻辑说明：reader.outline返回的是混合结构，书签对象和子列表交替出现，所以必须先判断isinstance(item, list)再决定是递归还是记录。get_destination_page_number把目标引用转成从 0 开始的页码，打印时加 1 还原成人看的页码。parent_title在循环里会被覆盖，这是有意的——同一层级的后续节点父标题应该跟着变，但跨层级递归时靠参数传递隔离，不会串。

参数说明：depth控制缩进和后续层级判断；page_no = -1是失效标记，后面写入前要过滤掉，否则会写出点不动的死书签。

3.2 页码偏移校正：扫描版 PDF 的必修课

扫描版 PDF 有个玄学问题：正文里印的页码和 PDF 物理页序号对不上，前面有封面、版权页、目录页，偏移量可能是 5 也可能是 12。直接按正文页码写书签，点进去全是错位。

def detect_offset(reader, sample_titles): """用几个已知标题在正文中的页码，反推物理页偏移""" # sample_titles: [(正文标题, 正文标注页码), ...] offsets = [] for title, printed_page in sample_titles: for i, page in enumerate(reader.pages): text = page.extract_text() or "" if title in text: # 物理页 i（0 基）对应正文第 printed_page 页 offsets.append(i - (printed_page - 1)) break if not offsets: return 0 # 取众数，避免个别页抽错文本带偏 return max(set(offsets), key=offsets.count)

逻辑说明：拿 3 到 5 个确定位置的标题做样本，在每页抽文本里找标题，找到就记录「物理页序号 - 正文页码 + 1」的差值，最后取出现次数最多的偏移量。取众数而不是平均值，是因为扫描件 OCR 偶尔会把某页文本抽乱，平均值会被个别异常值拉偏。

参数说明：sample_titles至少给 3 个，分布在不同章节；extract_text对纯图片扫描页返回空串，所以样本标题要选有文字层的页，或者先跑一遍 OCR。这一步是整个流程里最容易翻车的地方，后面避坑章节细说。

3.3 把读取结果落成中间表

读出来的数据别直接进写入环节，先落一份 CSV 或 JSON 中间表，人工扫一眼层级和页码对不对，比写完再改省事得多。

import csv rows = walk_outline(reader) with open("outline_dump.csv", "w", newline="", encoding="utf-8-sig") as f: writer = csv.writer(f) writer.writerow(["depth", "title", "page_1based", "parent"]) for depth, title, page_no, parent in rows: writer.writerow([depth, title, page_no + 1 if page_no >= 0 else "INVALID", parent])

encoding="utf-8-sig"是给 Excel 看的，不加打开是乱码。中间表的价值在于：批量处理几十份 PDF 时，先统一 dump 再统一核对，比一份份开 PDF 点书签快一个数量级。

4. 批量写入书签：从规则表到多级 outline

4.1 用标题正则从正文抽书签条目

没有现成书签的 PDF，得从正文抽。最常见的是按章节标题的正则匹配，比如「第X章」「X.X 小节」这类模式。

import re # 匹配「第3章 系统架构」和「3.2 数据流」两种标题 CHAPTER_RE = re.compile(r"^第\s*(\d+)\s*章\s+(.+)$") SECTION_RE = re.compile(r"^(\d+)\.(\d+)\s+(.+)$") def extract_headings(reader): """逐页抽文本，按行匹配标题，返回 [(层级, 标题, 页码0基), ...]""" items = [] for page_no, page in enumerate(reader.pages): text = page.extract_text() or "" for line in text.splitlines(): line = line.strip() m = CHAPTER_RE.match(line) if m: items.append((0, line, page_no)) continue m = SECTION_RE.match(line) if m: items.append((1, line, page_no)) return items

逻辑说明：先匹配章再匹配节，continue保证一行不会被两个正则重复命中。层级用 0 和 1 表示，写入时映射成父子关系。页码直接用当前页的 0 基序号，因为标题就在这一页上，不需要偏移校正——偏移只影响「正文标注页码」和「物理页」的换算，这里用的是物理页，天然对齐。

参数说明：正则里的^和$必须加，否则正文里引用「见第 3 章」也会被误抓；\s+兼容全角空格和多个空格。实际项目里标题格式五花八门，正则要按样本调，别指望一套通吃。

4.2 按层级调 add_outline_item 写多级书签

拿到(层级, 标题, 页码)列表后，写入的关键是维护「当前父节点」的栈。

from pypdf import PdfReader, PdfWriter def write_outline(src_path, dst_path, items): reader = PdfReader(src_path) writer = PdfWriter() writer.append(reader) # 保留原文档全部页面 parent_stack = [] # 栈顶是当前层级的父节点 for level, title, page_no in items: if page_no < 0 or page_no >= len(reader.pages): continue # 页码越界直接跳过，别写死书签 # 层级回退：栈深度大于当前层级时弹栈 while len(parent_stack) > level: parent_stack.pop() parent = parent_stack[-1] if parent_stack else None node = writer.add_outline_item(title, page_no, parent=parent) # 当前节点成为下一层的潜在父节点 if len(parent_stack) == level: parent_stack.append(node) else: parent_stack[level] = node with open(dst_path, "wb") as f: writer.write(f)

逻辑说明：parent_stack的长度始终等于「当前已建立的最大层级 + 1」。遇到层级回退先弹栈，再取栈顶当父节点。add_outline_item返回新节点对象，写完后把它压栈或替换对应位置，供后续子节点引用。writer.append(reader)而不是逐页add_page，是为了保留原文档的页面资源和元数据，逐页加会丢东西。

参数说明：parent=None表示一级书签；page_no是 0 基物理页；越界检查不能省，某次数据源里混进一个页码 999 的脏条目，不检查直接写，生成的 PDF 打开就报结构错误。

4.3 批量跑目录：一份规则表驱动多份 PDF

单份写完不算批量。真正的批量是：一份规则配置（标题正则、偏移量、层级映射），套用到整个目录下的 PDF。

from pathlib import Path def batch_process(input_dir, output_dir, offset_map=None): input_dir, output_dir = Path(input_dir), Path(output_dir) output_dir.mkdir(parents=True, exist_ok=True) for pdf in input_dir.glob("*.pdf"): offset = (offset_map or {}).get(pdf.name, 0) reader = PdfReader(str(pdf)) items = extract_headings(reader) # 应用偏移：物理页 = 抽取页 + offset items = [(lv, t, p + offset) for lv, t, p in items] write_outline(str(pdf), str(output_dir / pdf.name), items) print(f"done: {pdf.name}, {len(items)} bookmarks")

逻辑说明：offset_map按文件名给不同 PDF 配不同偏移，因为同一批手册的封面页数可能不一致。glob("*.pdf")只扫一层，需要递归换rglob。打印条目数是给自己看的，数量对不上说明正则漏抓了。

参数说明：offset为正表示物理页比抽取页靠后；output_dir单独开，绝不覆盖原文件——写坏了还有后悔药。

5. 避坑与排查：五条踩出来的记录

5.1 书签写进去但点不动

现象：生成的 PDF 侧边栏有标题，点击没反应，或者跳到第一页。原因：add_outline_item的page_no传了超出页数的值，或者传了None，pypdf 不报错但生成的目标引用是空的。解决：写入前统一做0 <= page_no < len(reader.pages)过滤，并在写完后重新PdfReader打开，遍历 outline 校验每个节点的get_destination_page_number是否有效，无效的整批回滚重跑。

5.2 加密 PDF 读取直接抛异常

现象：PdfReader初始化成功，但访问.outline或.pages时报FileNotDecryptedError。原因：文档有用户密码，pypdf 默认不自动解密。解决：先reader.decrypt("")试空密码（很多文档只设了权限密码没设打开密码），失败再走密码表；解密后再读 outline。注意decrypt返回 0 表示失败，别只看有没有抛异常。

5.3 中文标题写成乱码

现象：书签标题在阅读器里显示成方块或问号。原因：PDF 的/Title字符串编码和阅读器字体不匹配，pypdf 写入时按 UTF-16BE 存，但某些老阅读器只认 PDFDocEncoding。解决：标题里避免生僻字和特殊符号；写入前对标题做title.encode("utf-16-be")长度检查，超长截断；实在不行换 PyMuPDF 写，它对中文编码的处理更宽容。

5.4 层级错位，子书签挂到了错误的父节点下

现象：本该挂在「第 3 章」下的「3.2 节」跑到了「第 2 章」下面。原因：parent_stack的弹栈逻辑写错，层级回退时没弹干净，或者add_outline_item的parent传了上一个同级节点而不是父节点。解决：写入前把(层级, 标题)序列打印出来人工核对一遍；栈操作单独写单测，用固定输入断言输出树结构；parent永远取parent_stack[level - 1]，不取parent_stack[-1]。

5.5 批量跑一半中断，已处理的文件状态不明

现象：处理到第 17 份 PDF 时脚本崩了，前 16 份写没写、写到哪不知道。原因：没有断点记录，异常直接冒泡。解决：每份文件处理完往done.log追加一行文件名和条目数，重跑时先读 log 跳过已完成的；单份文件写入用临时文件 +os.replace原子替换，崩了也不会留下半截 PDF。

6. 进阶：把书签校验做成流水线的固定关卡

写到能跑只是及格线，真正让这套源码在批量场景下站住脚的，是写完之后的自动校验。我现在的习惯是：任何一次批量写入，必须过一遍「回读校验」，不过就整批标记失败，绝不人工抽查。

校验逻辑不复杂，但覆盖三个致命点：树深度是否和预期一致、每个节点的目标页是否有效、标题数量是否和输入条目数对得上。

def verify_outline(pdf_path, expected_count, expected_max_depth): reader = PdfReader(pdf_path) flat = walk_outline(reader) if len(flat) != expected_count: return False, f"count mismatch: {len(flat)} != {expected_count}" max_depth = max((d for d, _, _, _ in flat), default=-1) if max_depth != expected_max_depth: return False, f"depth mismatch: {max_depth} != {expected_max_depth}" invalid = [t for _, t, p, _ in flat if p < 0] if invalid: return False, f"invalid targets: {invalid[:3]}" return True, "ok"

逻辑说明：复用第 3 章的walk_outline，保证校验和读取用同一套解析逻辑，避免「读的时候对、校验的时候错」这种自欺欺人。expected_max_depth从输入条目里算，不写死。返回布尔值加原因字符串，批量脚本里直接if not ok: 记入失败清单。

参数说明：expected_count是写入前的条目数（过滤越界后的），不是原始抽取数；invalid[:3]只打印前三个，避免日志刷屏。

再往前一步，可以把「抽取 → 偏移校正 → 写入 → 校验」串成一条命令，用配置文件驱动：

配置文件的好处是，换一批 PDF 只改配置不改代码，正则调错了也不会污染源码。某次处理一批 60 多份的技术文档，偏移量从 3 到 14 不等，全靠offset_map一份份配，跑完校验 60 份全过，那种一次通过的踏实感比事后修 20 份错位书签强太多。

从那以后我每次批量写书签，都强制走一遍「dump 中间表 → 人工扫层级 → 写入 → 回读校验」四步，少一步都不放心。这套源码包把四步都拆成了独立函数，照着改参数就能接自己的文档。希望帮到你。

本文还有配套的精品资源，点击获取