简介：这份资源面向需要处理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 而不是 PyMuPDF2.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 是最省心的。库书签读取书签写入安装难度适用场景pypdf支持支持低（纯 Python）纯书签读写、轻量脚本PyMuPDF支持支持中（C 扩展）需要渲染/提取文本pdfrw支持部分支持低老项目兼容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 pypdfrequirements.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 写入逻辑，都强制先跑一遍小文件冒烟测试再批量，希望帮到你。本文还有配套的精品资源，点击获取
简介：这份资源面向需要处理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 而不是 PyMuPDF2.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 是最省心的。库书签读取书签写入安装难度适用场景pypdf支持支持低（纯 Python）纯书签读写、轻量脚本PyMuPDF支持支持中（C 扩展）需要渲染/提取文本pdfrw支持部分支持低老项目兼容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 pypdfrequirements.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 写入逻辑，都强制先跑一遍小文件冒烟测试再批量，希望帮到你。本文还有配套的精品资源，点击获取