简介：这份源码资源面向需要处理 PDF 目录结构的 Python 开发者，聚焦书签读取与批量写入两个典型场景，适合已掌握 Python 基础、希望用脚本替代手工整理电子书目录的中级学习者。压缩包共 2 个文件，以 1 个 py 脚本为主体，另附 1 个 gz 依赖包，整体约 40KB，体积轻量，便于直接解压运行与二次修改。资源围绕 PyPDF2 展开，演示如何用 getOutlines 提取书签的层级、标题与页码，并借助 JSON 结构化数据批量生成新书签，同时提示了页码从 0 开始、原文件不可直接修改等易错点。已有 2519 人学习下载，说明其在 PDF 自动化处理方向具备一定参考价值。读者可从中获得可复用的书签读写脚本、依赖安装思路与批量处理流程，快速套用到电子书目录整理、文档导航修复等实际任务中。
1. 从一份三百页的扫描件说起：Python 批量处理 PDF 书签到底能省多少事
上周帮一个做资料归档的朋友收拾烂摊子：三百多页的 PDF 合集，目录页是图片，书签栏空空如也，翻到第几章全靠 Ctrl+F 猜。他原本打算手动一页页加书签，我看了眼那密密麻麻的章节标题，直接劝退——这种活儿交给 Python 才是正解。这份源码干的就是这件事：读取已有 PDF 的书签树，解析出层级和页码，再按你给的规则批量写回新的书签结构。适合谁？做电子书整理、论文合集归档、扫描件目录重建的开发者，尤其是手里攒了一堆 PDF 却懒得一个个点开加书签的人。它不依赖重型 PDF 编辑软件，纯 Python 脚本跑完就出结果，改起来也方便，二次开发的门槛很低。
2. 技术选型与目录结构：为什么是 pypdf 而不是别的库
2.1 三个候选库的取舍
Python 处理 PDF 的库不少，常见的有 PyPDF2（现已并入 pypdf）、pdfplumber、PyMuPDF（fitz）。这份源码选的是 pypdf，原因很实际：书签操作本质是读写 PDF 的 Outlines 字典树，pypdf 对/Outlines、/Dest、/Page这些底层对象的封装最直接，读出来的Destination对象能拿到页码和标题，写回去也只需要构造add_outline_item调用。pdfplumber 强在文本抽取，书签这块基本没覆盖；PyMuPDF 功能全但依赖 C 扩展，装环境时偶尔会卡在编译上，对只想跑个脚本的人不友好。
我一般会这么判断：如果项目只做书签读写、不碰渲染和 OCR，pypdf 是性价比最高的选择。它的 API 稳定，社区文档也够用，遇到怪问题搜一下基本有答案。
2.2 目录结构长什么样
源码包解压后大致是这么个布局，我按功能给它归了类：
pdf_bookmark_tool/ ├── main.py # 入口，命令行参数解析 ├── reader.py # 书签读取与树形结构还原 ├── writer.py # 书签批量写入 ├── utils.py # 页码映射、标题清洗等工具函数 ├── config.py # 默认配置（编码、缩进、日志级别） └── samples/ # 示例 PDF 与书签模板这个拆分方式很朴素，但边界清楚：reader.py只负责把 PDF 里的书签抽成 Python 的嵌套字典，writer.py只负责把嵌套字典写回 PDF，main.py做编排。二次开发时想加“从目录页 OCR 识别标题”这种功能，只需要在reader.py旁边挂一个新模块，不用动写入逻辑。
2.3 核心依赖与安装
依赖就一个主库加一个辅助库，requirements.txt里通常是：
pip install pypdf pip install argparse # 标准库，实际不用单独装如果你的 PDF 里有中文书签，还要注意编码问题——pypdf 读出来的标题是str，但某些老文件里存的是 GBK 编码的字节串，直接打印会乱码。源码里在utils.py做了兜底解码，后面会讲到。
提示：装 pypdf 时建议锁定版本，比如
pypdf==4.x，因为 3.x 和 4.x 在add_outline_item的参数签名上有细微差别，跨版本跑容易报TypeError。
3. 书签读取模块拆解：把 PDF 的 Outlines 树还原成嵌套字典
3.1 读取入口与递归遍历
PDF 的书签在文件结构里是一棵双向链表式的树，每个节点有/Title、/Parent、/First、/Next等键。pypdf 的PdfReader.outline属性已经帮你做了一层扁平化，但它返回的是混合了列表和Destination对象的嵌套结构，直接遍历容易踩坑。源码里reader.py的核心函数是这样写的：
from pypdf import PdfReader def read_outline(pdf_path): reader = PdfReader(pdf_path) raw = reader.outline return _parse_nodes(reader, raw) def _parse_nodes(reader, nodes): result = [] for node in nodes: if isinstance(node, list): # 嵌套列表代表子层级，递归处理 result[-1]["children"] = _parse_nodes(reader, node) else: # Destination 对象，取标题和页码 title = node.title or "未命名" page_no = reader.get_destination_page_number(node) + 1 result.append({ "title": title.strip(), "page": page_no, "children": [] }) return result这段逻辑的关键在于isinstance(node, list)这个判断。pypdf 的outline返回结构里，子层级是以“列表套在父节点后面”的形式出现的，所以遇到列表就说明前一个节点有子书签，递归下去即可。get_destination_page_number返回的是从 0 开始的索引，加 1 才是人看的页码。
参数说明：pdf_path是输入文件路径；node.title可能为None，所以做了兜底；strip()是为了去掉标题里常见的首尾空格和换行符，扫描件生成的标题经常带这些脏字符。
3.2 中文标题的编码兜底
实际跑的时候，我遇到过标题打印出来是b'\xe7\xac\xac\xe4\xb8\x80\xe7\xab\xa0'这种字节串的情况。原因是某些 PDF 生成工具把标题存成了 PDFDocEncoding 或 GBK 字节流，pypdf 没自动转。utils.py里加了个清洗函数：
def clean_title(raw_title): if isinstance(raw_title, bytes): for enc in ("utf-8", "gbk", "latin-1"): try: return raw_title.decode(enc).strip() except UnicodeDecodeError: continue return str(raw_title).strip()按 utf-8、gbk、latin-1 的顺序试解码，哪个成功用哪个。latin-1 是兜底，因为它对任意字节都不会抛异常，虽然可能解出乱码，但至少不会让程序崩掉。这个顺序不能反，gbk 放前面会把一些 utf-8 字节误判。
3.3 页码映射的坑：Dest 不一定是 Page
有些 PDF 的书签目标不是直接指向页面，而是指向一个命名目标（Named Destination），这时候get_destination_page_number可能返回 -1。源码里的处理是：
page_no = reader.get_destination_page_number(node) if page_no < 0: # 命名目标，尝试从 reader.named_destinations 里找 dest_name = node.get("/D") if hasattr(node, "get") else None if dest_name and dest_name in reader.named_destinations: page_no = reader.get_destination_page_number( reader.named_destinations[dest_name] )这段不是所有 PDF 都会触发，但一旦遇到，不加处理就会写出页码为 0 的坏书签。我的血泪经验是：读完之后先打印一遍统计，看看有多少条页码是 -1 或 0，心里有数再往下走。
4. 批量写入模块：从嵌套字典到 add_outline_item 的完整链路
4.1 写入的基本调用
pypdf 写书签的 API 是PdfWriter.add_outline_item(title, page_number, parent=None)，其中parent传上一级返回的书签对象就能形成层级。writer.py的核心递归：
from pypdf import PdfReader, PdfWriter def write_outline(src_path, dst_path, tree): reader = PdfReader(src_path) writer = PdfWriter() writer.append(reader) # 先把所有页面搬过来 def _add(nodes, parent=None): for item in nodes: # page 是 1-based，add_outline_item 要 0-based outline = writer.add_outline_item( item["title"], item["page"] - 1, parent=parent ) if item.get("children"): _add(item["children"], parent=outline) _add(tree) with open(dst_path, "wb") as f: writer.write(f)这里有个容易翻车的点：writer.append(reader)会把原 PDF 的页面和元数据都带过来，但不会带原书签。所以如果你是想“在原书签基础上追加”，得先把原书签读出来合并进tree，再统一写。源码默认是覆盖式写入，main.py里通过--merge参数控制是否合并。
参数说明：src_path是原始 PDF；dst_path是输出路径，建议不要和源文件同名，避免写一半失败把原文件毁了；tree就是第 3 章读出来的嵌套字典结构。
4.2 批量处理的编排逻辑
“批量”体现在两个层面：一是单个 PDF 内批量写多条书签，二是多个 PDF 文件批量处理。main.py里对目录的遍历是这样组织的：
import os from pathlib import Path def batch_process(input_dir, output_dir, template): input_dir = Path(input_dir) output_dir = Path(output_dir) output_dir.mkdir(parents=True, exist_ok=True) for pdf_file in input_dir.glob("*.pdf"): tree = load_template_for(pdf_file, template) dst = output_dir / pdf_file.name try: write_outline(str(pdf_file), str(dst), tree) print(f"[OK] {pdf_file.name}") except Exception as e: print(f"[FAIL] {pdf_file.name}: {e}")load_template_for是个可替换的钩子函数，默认从samples/下找同名.json书签模板；如果你有统一的章节结构（比如所有 PDF 都是同一本书的不同分册），可以改成返回固定模板。这个设计留了扩展口，二次开发时把 OCR 识别结果塞进来就行。
4.3 书签模板的 JSON 格式
为了让批量写入可配置，源码约定了一个 JSON 模板格式，和读出来的嵌套字典完全同构：
[ { "title": "第一章 概述", "page": 1, "children": [ {"title": "1.1 背景", "page": 2, "children": []}, {"title": "1.2 目标", "page": 5, "children": []} ] } ]这样读和写共用一套数据结构，中间不需要转换。我一般会先用读取模式跑一遍目标 PDF，把结果导出成 JSON，人工改改页码和标题，再用写入模式灌回去——比从零手写模板快得多。
注意：JSON 里的
page是 1-based 页码，和 PDF 阅读器显示的一致；如果你的模板是从别的工具导出的 0-based 数据，记得统一减 1 或加 1，这个错位是最常见的“书签全偏一页”来源。
5. 避坑与排查：那些让我加班到深夜的书签问题
5.1 写入后书签全变成“未命名”
现象：跑完脚本，PDF 书签栏里一堆空白条目。原因：item["title"]取到了None或空字符串，add_outline_item接受空标题但不报错。解决：在_add里加一道校验，title = item.get("title") or f"第{item['page']}页"，空标题用页码兜底，至少能看出是哪条。
5.2 中文标题写入后乱码
现象：读取时正常，写回去打开变成问号或方块。原因：PdfWriter写标题时按 PDF 标准用 UTF-16BE 编码，但如果你的title本身是错误解码的字节串（比如把 GBK 当 utf-8 解了），写进去就是错的。解决：写入前统一走一遍clean_title，确保传进去的是正确的str。我现在的习惯是读出来先json.dumps(ensure_ascii=False)存一份，肉眼确认标题对了再写。
5.3 大文件写入内存爆掉
现象：处理 500 页以上的 PDF 时进程被系统杀掉。原因：writer.append(reader)会把整个文档加载进内存，加上原 reader 还占着一份，内存翻倍。解决：如果只是加书签不改页面，可以用PdfWriter(clone_from=src_path)的增量模式，或者分批次处理——先写书签到临时文件，再合并。源码里对超过 200 页的文件会打印内存提示，但没做自动降级，这块留给二次开发补。
5.4 页码偏移一页
现象：书签点进去总是差一页。原因：PDF 的封面、目录页可能用了罗马数字页码，而get_destination_page_number返回的是物理页索引，两者不一致。解决：在config.py里加一个page_offset配置，写入时统一page - 1 + offset。这个偏移量因文件而异，批量处理前最好抽一两个文件手动核对。
5.5 加密 PDF 直接报错
现象：PdfReadError: File has not been decrypted。原因：源文件带打开密码。解决：PdfReader(pdf_path)之后判断reader.is_encrypted，是的话调reader.decrypt(password)，密码从命令行参数或环境变量传。源码默认没处理加密，遇到就跳过并记日志，避免批量任务卡死在一个文件上。
6. 二次开发改造思路：把书签工具接进自己的归档流水线
这份源码的骨架已经够用，但真要接进实际业务，我一般会做三处改造。第一处是把load_template_for换成“从目录页文本自动生成书签树”——用 pdfplumber 抽目录页文本，正则匹配“第X章 + 页码”的模式，生成 JSON 模板再走写入流程。这样扫描件只要目录页是文字层（哪怕是 OCR 出来的），就能全自动出书签。第二处是加一个校验步骤：写入完成后重新用read_outline读一遍输出文件，和输入模板做 diff，条数和页码对不上就报警，避免“以为写成功了其实静默失败”。第三处是把单文件处理改成队列消费，配合concurrent.futures开 4 个进程跑，几百个 PDF 的归档任务从半小时压到几分钟。
验证方法很简单：准备三个样本——一个带完整书签的正常 PDF、一个书签为空的扫描件、一个加密 PDF，跑完看输出目录里前两个成功、第三个被跳过并记日志，就说明主链路和异常分支都通了。
改造时有个细节值得注意：add_outline_item的parent参数传的是上一次调用返回的对象，这个对象只在当前writer实例内有效，跨文件复用会报错。所以批量处理时每个文件都要新建PdfWriter，别想着复用。
| 改造点 | 改动文件 | 预估工作量 |
|---|---|---|
| 目录页自动识别 | 新增ocr_reader.py | 半天 |
| 写入后校验 | writer.py加verify() | 1 小时 |
| 多进程批量 | main.py换执行器 | 2 小时 |
| 加密文件支持 | reader.py加 decrypt | 半小时 |
从那以后我每次做批量写入，都强制先跑一遍“读-导出 JSON-人工抽查-再写”的流程，绝不直接覆盖源文件。这个习惯救过我两次——一次是模板页码整体错位，一次是某本 PDF 的书签目标全是命名目标，提前发现总比交付后被退回强。希望帮到你。
本文还有配套的精品资源，点击获取
