Python批量处理PDF书签：pypdf实现读取与写入源码

简介：这份资源面向需要处理PDF文档的Python开发者与办公自动化爱好者，聚焦PDF书签的读取与批量写入这一常见需求。包内共2个文件，以1个py脚本和1个gz压缩包为主，前者是可直接运行的书签处理源码，后者为配套依赖库，整体约40KB，轻量易部署。已有2516人学习下载，说明该方案在实际场景中具备一定参考价值。源码演示了如何借助PyPDF2读取现有书签的层级、标题与跳转页码，并支持从JSON结构化数据批量生成新书签写入PDF，同时提示了PyPDF2无法直接修改原文件、需另存新文件等注意事项。读者可据此快速搭建书签管理脚本，理解PDF目录结构与页码映射逻辑，并在此基础上扩展水印、权限等处理，适合作为Python文档处理入门的实操参考。

1. 从一份 800 页的 PDF 说起：书签批量处理到底能省多少事

前阵子帮一个做资料归档的朋友处理一批扫描版技术手册，单个 PDF 动辄七八百页，目录页倒是扫进去了，但书签栏空空如也。他原本的做法是手动翻到每一章开头，右键「添加书签」，再敲标题——一本手册搞完接近一小时，十几本下来直接崩溃。后来我用 Python 写了个小工具，先读取一份已经整理好的 PDF 书签结构，再批量写入到其他同版式的 PDF 里，整个过程压缩到几秒钟。这就是「python 实现 pdf 书签读取、批量写入源码」要解决的问题：把 PDF 书签从手工劳动变成可复用的代码流程。它适合经常处理电子书、技术文档、扫描归档的开发者，也适合想拿一个真实小项目练手 PDF 底层操作的人。核心依赖就一个 pypdf，不需要额外装一堆重型库，跑起来门槛很低。

2. 技术选型与目录结构：为什么是 pypdf 而不是 PyMuPDF

2.1 库的取舍：pypdf、PyMuPDF、pdfrw 怎么选

处理 PDF 书签，绕不开三个候选库：pypdf、PyMuPDF（fitz）、pdfrw。我一开始也纠结过，后来按「只做书签读写」这个目标筛了一遍，结论很明确。

PyMuPDF 功能最强，读写书签都支持，还能渲染页面、提取文本，但它是 C 扩展编译的 wheel，体积大，某些精简环境装起来会翻车。pdfrw 轻量，但维护活跃度一般，对较新的 PDF 结构兼容性偶尔出玄学问题。pypdf 是纯 Python 实现，pip 一条命令搞定，API 清晰，reader.outline和writer.add_outline_item这对组合刚好覆盖「读取 + 批量写入」的全部需求。

所以这个项目的选型逻辑是：功能刚好够用，依赖尽量少，跨平台不折腾。如果你后续还要提取文本或转图片，那再上 PyMuPDF 也不迟，但单纯做书签，pypdf 是最省心的。

2.2 项目目录结构

这个工具不需要复杂工程化，但目录还是分清楚比较好维护。我一般会这样组织：

pdf_bookmark_tool/ ├── main.py # 入口，命令行参数解析 ├── bookmark_reader.py # 读取源 PDF 书签，输出结构化数据 ├── bookmark_writer.py # 将书签数据批量写入目标 PDF ├── utils.py # 页码偏移、标题清洗等辅助函数 ├── requirements.txt # 依赖清单 └── samples/ ├── source.pdf # 带书签的模板 PDF └── target.pdf # 待写入书签的 PDF

拆成 reader / writer 两个模块的好处是：读取和写入可以独立测试。比如你只想导出某本书的书签做备份，直接调 reader 就行；只想把一份 JSON 书签写进新 PDF，调 writer 即可。utils.py里放页码偏移计算，是因为扫描版 PDF 经常存在「物理页码」和「逻辑页码」差几页的情况，这个后面会细讲。

2.3 依赖安装与环境准备

依赖只有 pypdf 一个，Python 版本建议 3.8 以上。安装命令：

pip install pypdf

如果你用的是虚拟环境（推荐），先建环境再装：

python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install pypdf

requirements.txt里写一行pypdf>=4.0.0即可。这里注意：pypdf 在 3.x 到 4.x 之间有过 API 调整，老教程里常见的PdfFileReader已经废弃，现在统一用PdfReader/PdfWriter。如果你复制了网上的老代码报AttributeError，八成就是这个原因。

3. 核心模块拆解：书签读取与批量写入的完整链路

3.1 读取书签：outline 的嵌套结构怎么解析

pypdf 读取书签的入口是reader.outline，它返回的是一个嵌套列表。理解这个结构是整件事的关键——很多新手卡在这里，是因为直接把它当成平铺列表处理，结果遇到多级书签就乱了。

先看读取代码：

from pypdf import PdfReader def read_bookmarks(pdf_path): """读取 PDF 书签，返回嵌套的字典列表""" reader = PdfReader(pdf_path) outline = reader.outline return parse_outline(reader, outline) def parse_outline(reader, outline, level=0): """递归解析 outline 嵌套结构""" result = [] for item in outline: # 如果是列表，说明是上一项的 children，递归处理 if isinstance(item, list): result[-1]["children"] = parse_outline(reader, item, level + 1) else: # item 是 Destination 对象，取标题和页码 title = item.title page_num = reader.get_destination_page_number(item) result.append({ "title": title, "page": page_num, "level": level, "children": [] }) return result

逻辑说明：outline里每个元素要么是一个Destination对象（代表一条书签），要么是一个list（代表前一条书签的子书签集合）。所以解析时必须递归，遇到 list 就挂到上一条的children上。reader.get_destination_page_number(item)返回的是从 0 开始的页码索引，写入时需要保持一致。

参数说明：level用来记录层级深度，方便后续写入时还原结构。title是书签显示文字，page是目标页索引。这个结构可以直接json.dump导出，作为书签模板复用。

3.2 写入书签：add_outline_item 的父子关系怎么建

写入比读取稍微绕一点，因为add_outline_item需要你手动维护父子引用。它的签名是add_outline_item(title, page_number, parent=None, before=None)，返回新书签的引用，这个引用要传给子书签当parent。

from pypdf import PdfReader, PdfWriter def write_bookmarks(src_pdf, bookmark_data, output_pdf, offset=0): """把书签数据写入 PDF，offset 用于页码偏移校正""" reader = PdfReader(src_pdf) writer = PdfWriter() # 先把所有页面复制进 writer for page in reader.pages: writer.add_page(page) def add_items(items, parent=None): for item in items: # 页码偏移：物理页 = 逻辑页 + offset target_page = item["page"] + offset # 越界保护，防止写入非法页码 if target_page < 0 or target_page >= len(writer.pages): continue new_ref = writer.add_outline_item( title=item["title"], page_number=target_page, parent=parent ) # 有子书签就递归，把当前引用作为 parent 传下去 if item.get("children"): add_items(item["children"], parent=new_ref) add_items(bookmark_data) with open(output_pdf, "wb") as f: writer.write(f)

逻辑说明：先把源 PDF 的页面全部复制到 writer，再逐条添加书签。parent参数是建立层级的关键——顶级书签 parent 为 None，子书签 parent 传父书签的返回值。offset处理页码偏移，扫描版 PDF 经常需要。

参数说明：src_pdf是待写入书签的 PDF，bookmark_data是 3.1 解析出来的结构，output_pdf是输出路径，offset默认 0，正数表示逻辑页码比物理页码小。越界保护那行别省，否则遇到脏数据会直接抛异常中断整个批量流程。

3.3 批量处理：一次给多个 PDF 写入同一套书签

单文件跑通后，批量就是套一层循环。常见场景是：一批同版式的 PDF，书签结构完全一样，只是文件名不同。

import os from bookmark_reader import read_bookmarks from bookmark_writer import write_bookmarks def batch_process(template_pdf, target_dir, output_dir, offset=0): """用模板 PDF 的书签，批量写入目标目录下所有 PDF""" bookmarks = read_bookmarks(template_pdf) os.makedirs(output_dir, exist_ok=True) for filename in os.listdir(target_dir): if not filename.lower().endswith(".pdf"): continue src = os.path.join(target_dir, filename) dst = os.path.join(output_dir, filename) try: write_bookmarks(src, bookmarks, dst, offset=offset) print(f"[OK] {filename}") except Exception as e: # 单个失败不影响其他文件 print(f"[FAIL] {filename}: {e}") if __name__ == "__main__": batch_process("samples/source.pdf", "samples/targets", "output", offset=2)

逻辑说明：先读一次模板书签，避免每个文件重复解析。循环里对每个 PDF 调write_bookmarks，用 try/except 包住，保证单个文件出错不中断整批。offset=2是示例，实际值要根据你的 PDF 调整。

参数说明：template_pdf是带书签的模板，target_dir是待处理目录，output_dir是输出目录（不覆盖原文件，安全）。这里我习惯输出到单独目录，而不是原地修改——原地改一旦出错，后悔药都没得吃。

4. 避坑与常见问题：页码偏移、加密 PDF、书签丢失怎么排查

4.1 现象：书签写进去了，但点击跳转的页码全错

原因：扫描版 PDF 的物理页码和书签逻辑页码不一致。比如正文从第 10 页开始，但 PDF 文件里前面有封面、版权页，实际索引是 12。你按逻辑页码写，跳转就偏了。

解决：用offset参数校正。先手动翻到某一章，记下 PDF 阅读器显示的页码和实际索引的差值，把这个差值传给offset。如果不同章节偏移不一致，说明这份 PDF 结构不规整，得逐条调整bookmark_data里的page值，不能靠统一 offset 解决。

4.2 现象：读取时报PdfReadError: File has not been decrypted

原因：目标 PDF 带密码或权限加密，pypdf 默认拒绝读取。

解决：如果只是权限密码（空用户密码），用reader.decrypt("")尝试解密。如果有真实密码，得先拿到密码再reader.decrypt(password)。注意：解密只影响读取，写入时 writer 是新建的，不受原加密限制。

reader = PdfReader(pdf_path) if reader.is_encrypted: reader.decrypt("") # 空密码尝试

4.3 现象：写入后书签层级全平了，子书签变成顶级

原因：add_outline_item的parent参数没传对。常见错误是递归时忘了把当前引用传下去，或者把parent传成了None。

解决：检查add_items递归调用那行，确认parent=new_ref传的是当前书签的返回值，而不是外层 parent。层级结构完全靠这个引用链维持，断一环就全平。

4.4 现象：批量处理到一半卡住，某个文件特别慢

原因：某个 PDF 页数特别多，或者包含大量嵌入对象，add_page逐页复制耗时。

解决：加进度输出和超时意识。可以在循环里打印当前文件名和页数，定位是哪个文件拖慢。如果确实有大文件，考虑用writer.append(reader)替代逐页add_page，前者在某些版本下更快，但要注意它会保留原文件的部分元数据，可能和你的预期不符。

4.5 现象：输出文件体积暴涨

原因：add_page复制页面时，某些 PDF 的资源对象被重复嵌入。

解决：这是 pypdf 的已知行为，纯书签操作一般不会导致暴涨，但如果原 PDF 本身有冗余资源，复制后会放大。可以先用writer.compress_identical_objects()去重，再写出。如果体积仍然异常，检查是不是把同一份页面复制了多次。

5. 二次开发与改造：从能跑到好用，我踩过的几个坑

5.1 把书签导出成 JSON 模板，实现跨文档复用

最实用的改造是加一个导出功能：把读取到的书签结构存成 JSON，下次直接读 JSON 写入，不再依赖模板 PDF。这样你可以手工编辑 JSON 调整标题和页码，灵活性高很多。

import json def export_bookmarks(pdf_path, json_path): data = read_bookmarks(pdf_path) with open(json_path, "w", encoding="utf-8") as f: json.dump(data, f, ensure_ascii=False, indent=2) def import_bookmarks(json_path): with open(json_path, "r", encoding="utf-8") as f: return json.load(f)

ensure_ascii=False别漏，否则中文标题会变成\uXXXX转义，虽然能用但没法读。导出后你可以用编辑器批量改标题，比如把「Chapter 1」统一替换成「第一章」，再写回去。

5.2 加一个页码自动探测：用文本匹配定位章节

手动填 offset 终究麻烦。进阶做法是用 pypdf 提取每页文本，匹配章节标题关键词，自动算出页码。思路是：遍历页面，page.extract_text()拿到文本，用正则找「第X章」这类模式，命中就记录页码。

import re def detect_chapter_pages(pdf_path, pattern=r"第[一二三四五六七八九十\d]+章"): reader = PdfReader(pdf_path) hits = [] for i, page in enumerate(reader.pages): text = page.extract_text() or "" if re.search(pattern, text): hits.append(i) return hits

这个方法的局限是：扫描版 PDF 没有文本层，extract_text返回空，得先做 OCR。所以它适合电子版 PDF，扫描版还是老实手动校 offset。我一般会把这个探测结果和模板书签做比对，差多少就设多少 offset，比纯手工试快得多。

5.3 改造时的验证习惯

每次改完写入逻辑，我都会拿一个 3 页的小 PDF 做冒烟测试：写两条顶级书签、一条子书签，然后用阅读器打开确认跳转和层级。小文件验证通过再上批量，能省掉大量排查时间。另外，输出目录永远单独建，不覆盖原文件——这个习惯帮我躲过好几次「写坏了原稿」的事故。

从那以后我每次动 PDF 写入逻辑，都强制先跑一遍小文件冒烟测试再批量，希望帮到你。

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