简介这份源码资源面向需要处理 PDF 目录结构的 Python 开发者聚焦书签读取与批量写入两个典型场景适合已掌握 Python 基础、希望用脚本替代手工整理电子书目录的中级学习者。压缩包共 2 个文件以 1 个 py 脚本为主体另附 1 个 gz 依赖包整体约 40KB体积轻量便于直接解压运行与二次修改。资源围绕 PyPDF2 展开演示如何用 getOutlines 提取书签的层级、标题与页码并借助 JSON 结构化数据批量生成新书签同时提示了页码从 0 开始、原文件不可直接修改等易错点。已有 2519 人学习下载说明其在 PDF 自动化处理方向具备一定参考价值。读者可从中获得可复用的书签读写脚本、依赖安装思路与批量处理流程快速套用到电子书目录整理、文档导航修复等实际任务中。1. 从一份三百页的扫描件说起Python 批量处理 PDF 书签到底能省多少事上周帮一个做资料归档的朋友收拾烂摊子三百多页的 PDF 合集目录页是图片书签栏空空如也翻到第几章全靠 CtrlF 猜。他原本打算手动一页页加书签我看了眼那密密麻麻的章节标题直接劝退——这种活儿交给 Python 才是正解。这份源码干的就是这件事读取已有 PDF 的书签树解析出层级和页码再按你给的规则批量写回新的书签结构。适合谁做电子书整理、论文合集归档、扫描件目录重建的开发者尤其是手里攒了一堆 PDF 却懒得一个个点开加书签的人。它不依赖重型 PDF 编辑软件纯 Python 脚本跑完就出结果改起来也方便二次开发的门槛很低。2. 技术选型与目录结构为什么是 pypdf 而不是别的库2.1 三个候选库的取舍Python 处理 PDF 的库不少常见的有 PyPDF2现已并入 pypdf、pdfplumber、PyMuPDFfitz。这份源码选的是 pypdf原因很实际书签操作本质是读写 PDF 的 Outlines 字典树pypdf 对/Outlines、/Dest、/Page这些底层对象的封装最直接读出来的Destination对象能拿到页码和标题写回去也只需要构造add_outline_item调用。pdfplumber 强在文本抽取书签这块基本没覆盖PyMuPDF 功能全但依赖 C 扩展装环境时偶尔会卡在编译上对只想跑个脚本的人不友好。我一般会这么判断如果项目只做书签读写、不碰渲染和 OCRpypdf 是性价比最高的选择。它的 API 稳定社区文档也够用遇到怪问题搜一下基本有答案。2.2 目录结构长什么样源码包解压后大致是这么个布局我按功能给它归了类pdf_bookmark_tool/ ├── main.py # 入口命令行参数解析 ├── reader.py # 书签读取与树形结构还原 ├── writer.py # 书签批量写入 ├── utils.py # 页码映射、标题清洗等工具函数 ├── config.py # 默认配置编码、缩进、日志级别 └── samples/ # 示例 PDF 与书签模板这个拆分方式很朴素但边界清楚reader.py只负责把 PDF 里的书签抽成 Python 的嵌套字典writer.py只负责把嵌套字典写回 PDFmain.py做编排。二次开发时想加“从目录页 OCR 识别标题”这种功能只需要在reader.py旁边挂一个新模块不用动写入逻辑。2.3 核心依赖与安装依赖就一个主库加一个辅助库requirements.txt里通常是pip install pypdf pip install argparse # 标准库实际不用单独装如果你的 PDF 里有中文书签还要注意编码问题——pypdf 读出来的标题是str但某些老文件里存的是 GBK 编码的字节串直接打印会乱码。源码里在utils.py做了兜底解码后面会讲到。提示装 pypdf 时建议锁定版本比如pypdf4.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, parentNone)其中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, parentNone): for item in nodes: # page 是 1-basedadd_outline_item 要 0-based outline writer.add_outline_item( item[title], item[page] - 1, parentparent ) if item.get(children): _add(item[children], parentoutline) _add(tree) with open(dst_path, wb) as f: writer.write(f)这里有个容易翻车的点writer.append(reader)会把原 PDF 的页面和元数据都带过来但不会带原书签。所以如果你是想“在原书签基础上追加”得先把原书签读出来合并进tree再统一写。源码默认是覆盖式写入main.py里通过--merge参数控制是否合并。参数说明src_path是原始 PDFdst_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(parentsTrue, exist_okTrue) 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_asciiFalse)存一份肉眼确认标题对了再写。5.3 大文件写入内存爆掉现象处理 500 页以上的 PDF 时进程被系统杀掉。原因writer.append(reader)会把整个文档加载进内存加上原 reader 还占着一份内存翻倍。解决如果只是加书签不改页面可以用PdfWriter(clone_fromsrc_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 的书签目标全是命名目标提前发现总比交付后被退回强。希望帮到你。本文还有配套的精品资源点击获取