简介面向需要处理PDF文档书签的Python开发者这套源码包基于PyPDF2库解决了从既有PDF中读取书签层级、标题与页码以及将外部书签定义批量写入新PDF的两类常见需求。资源共2个文件包含一个可直接运行的Python脚本和一份PyPDF2依赖库源码包zip整体仅40KB轻量易部署。目前已有2513人学习下载。脚本中read_bookmarks函数利用getOutlines()递归解析书签节点并打印层级信息write_bookmarks函数则通过读取JSON结构化数据为每个条目创建Destination与OutlineItem配合PdfFileWriter生成带书签的新文件完整演示了PyPDF2在目录管理上的典型用法。代码注释清晰适合希望掌握PDF内容结构、自动化整理电子书目录或批量维护书签索引的中初级Python工程师参考学习。1. 批量处理 PDF 书签Python 这套源码能直接抄作业做 PDF 自动化处理的老手都知道书签PDF 大纲/Outlines这玩意儿看着不起眼真批量操作起来比改文本还折腾。市面上能写书签的工具不少但要么收费、要么只能在图形界面里一个个点几十个文件下来手都得抽筋更麻烦的是很多 PDF 是从扫描件或网页打印来的根本没有书签后期想按章节加目录手动补的工程量能让人直接放弃。这套 Python 源码解决的就是这个痛点读取现有 PDF 的书签结构、批量往一批 PDF 里写入指定书签、还能按页码偏移量微调定位。我自己拿它处理过一百多份技术手册把从网上抓下来的无书签 PDF 按章节重新组织了目录整个过程全命令行跑完稳定性和效率比用 GUI 工具高一个量级。适合需要批量整理电子书、技术文档、论文合集的开发者和文档工程师也适合做数据清洗时顺手把 PDF 目录结构捋一遍的人。下面从实现原理到踩坑细节逐一拆开讲。2. 书签读写的核心机制先搞懂 PDF 结构再动手2.1 PDF 大纲不是文本是一棵节点树PDF 书签在规范里叫大纲Outline存储在文件尾部附近的交叉引用表之后属于文档的可选内容。它的逻辑结构是一棵树根节点下面挂一级章节每个一级章节又能挂二级、三级子节点节点之间通过/First、/Last、/Next、/Prev以及/Parent这几个键互相引用。每个书签节点至少包含两部分/Title是显示名称/Dest或/A则指向一个页面位置。/Dest有两种写法一种直接写页码和页面内的坐标另一种通过命名目的地引用实际解析时两种情况都要兼容否则有的 PDF 读出来书签是空的。这套源码读取书签时并没有用第三方重库而是直接基于pypdf老版本叫PyPDF2来操作。pypdf把大纲树封装成了outline属性遍历时返回的每一项要么是字典、要么是列表字典代表一个具体书签项列表则代表一组子树。新手容易在这块翻车——因为pypdf返回的书签结构表面上是嵌套列表但每个节点的children其实是通过列表的嵌套关系隐式表达的。源码里专门写了个递归函数把嵌套结构拍平成带缩进级别的列表这样后续无论是打印还是按规则过滤都方便。读操作的核心逻辑并不复杂关键在对目的地页码的解析。pypdf里拿到一个书签目的地的标准姿势是通过reader.get_destination_page_number(bookmark)获取页码但前提是书签的/Dest是明确的页面引用如果遇到/A动作类型的书签比如点击后执行跳转或打开 URLget_destination_page_number会直接抛异常必须在调用前判断节点类型。源码里对每个节点先检查是否有/A键有就走动作分支没有才当普通目的地处理这样能把常见的“外部链接型书签”和“内部跳转型书签”区分开避免读到一半崩溃。from pypdf import PdfReader def extract_outline(reader, outline_elem, level0, resultNone): if result is None: result [] if isinstance(outline_elem, list): for item in outline_elem: extract_outline(reader, item, level, result) else: try: page_no reader.get_destination_page_number(outline_elem) except Exception: page_no -1 result.append({ title: outline_elem.title, level: level, page: page_no, raw: outline_elem }) # 子节点通过 /First 链式访问pypdf 已封装为嵌套结构 for child in outline_elem.children: extract_outline(reader, child, level 1, result) return result reader PdfReader(sample.pdf) bookmarks extract_outline(reader, reader.outline) for bm in bookmarks: print(f[{ * bm[level]}] {bm[title]} - {bm[page]})上面这段代码做了三件事把pypdf返回的嵌套项递归遍历每个书签节点取出标题和页码同时记录缩进层级。注意page_no的异常兜底遇到-1就说明这个书签要么是外部链接要么是特殊动作后续写书签时可以跳过或单独标记。参数方面level初始传 0递归子节点时加 1这样缩进级别和 PDF 大纲树的层级能对应上。实际跑批量的场景里我一般会在这个结果里加个过滤条件只保留page 0的节点把纯链接型书签剔除后再做后续操作。2.2 页码偏移写入书签前必须先算清楚读取只是准备工作真正批量写书签时最常见的需求是给一整批 PDF 的前面统一插入几页封面或目录页然后原有书签的页码全部后移。当然也有反向场景从某个 PDF 里抽取部分页面生成新文件新文件的书签页码需要整体减掉一个偏移量。这套源码里专门预留了offset参数作用就是干这个。写书签的底层逻辑是用PdfWriter先拷贝原文档所有页面再通过writer.add_outline_item(title, page_number, parentNone)把每个书签逐条挂上去。add_outline_item的page_number参数是零基页码而 PDF 规范里用户看到的页码通常是一基这里特别容易搞混。源码的约定是所有输入输出统一用一基页码内部计算时再减一这样和大多数 PDF 阅读器显示的页码保持一致。from pypdf import PdfReader, PdfWriter def write_bookmarks(src_path, dst_path, bookmark_list, offset0): reader PdfReader(src_path) writer PdfWriter() for page in reader.pages: writer.add_page(page) for item in bookmark_list: # item: {title: str, page: int, level: int} target_page item[page] - 1 offset # 转零基并加偏移 parent None if item[level] 1 and item.get(parent_id): parent writer.bookmark_registry.get(item[parent_id]) writer.add_outline_item( titleitem[title], page_numbertarget_page, parentparent ) with open(dst_path, wb) as f: writer.write(f)逻辑说明add_outline_item的page_number接收的是零基页码所以从一基转零基必须减一offset统一在转换完成后叠加正数表示向后偏移负数表示向前。parent参数控制层级关系None表示挂到根节点下也就是一级书签要挂二级和三级书签必须把父节点的书签对象传进来。writer.bookmark_registry是pypdf内部维护书签对象引用的机制但实际循环写入时必须先保存每个新书签的返回值否则后面找父级会落空。参数方面bookmark_list里的level字段目前只影响是否尝试找父级真正的树形结构还得靠列表中title的缩进顺序来保证——这一点在处理多级书签时是个大坑后面避坑章节会细说。3. 批量处理的脚本设计从单文件到整个目录一次跑完3.1 文件清单与书签来源的组织方式当文件数量超过几十个时最忌讳的就是把书签数据硬编码在脚本里。这套源码的推荐做法是用一个 JSON 文件描述每个 PDF 对应的书签树脚本统一读 JSON 再批量执行。JSON 的结构大致是顶层数组每个元素包含input源文件路径、output输出文件路径、offset页码偏移量和bookmarks书签数组。书签数组里的每项用title、page、level描述level从 1 开始1 是一级章节2 是二级3 是三级最多支持到 4 级再深的意义不大。这么做的好处有三点第一书签数据和处理逻辑分离改目录结构不用动代码第二JSON 天然支持层级可以严格对照书籍的章节目录录入第三同一个源文件可以生成多套不同书签顺序的版本只要在 JSON 里写多个输出项就行。编辑 JSON 时我会用支持括号配对的编辑器避免逗号或花括号写错导致整个批量任务报错。读取 JSON 的代码片段不复杂重点是校验逻辑。路径不能写死要用相对路径或绝对路径根据运行环境动态拼接page字段必须大于等于 1且最好不超过源 PDF 的总页数否则写入的书签指向不存在的页面阅读器打开时通常会忽略或跳到最后一页。源码里对这种数据做了前置校验校验失败的文件会在日志里标红然后继续处理后面的不会因为一个坏数据让整批任务中断。3.2 多级书签的父子挂载用返回值建索引接着上面写书签那段代码说pypdf的add_outline_item在创建二级书签时需要把一级书签的对象作为parent传进去。而这个对象不是凭空造的是add_outline_item第一次创建一级书签时返回的。常见的错误写法是每创建一个书签都重新查一遍writer.outline或用find_bookmark这在书签数量少时没问题但批量场景下性能差且容易找错目标。正确做法是在循环里维护一个“最近的一级书签”和“最近的二级书签”引用根据当前项的level判断该挂到哪个父节点上。def write_nested_bookmarks(writer, bookmark_list): level_1_ref None level_2_ref None level_3_ref None for item in bookmark_list: lv item[level] page item[page] - 1 item.get(offset, 0) if lv 1: level_1_ref writer.add_outline_item(item[title], page, parentNone) level_2_ref None level_3_ref None elif lv 2: level_2_ref writer.add_outline_item(item[title], page, parentlevel_1_ref) level_3_ref None elif lv 3: level_3_ref writer.add_outline_item(item[title], page, parentlevel_2_ref) elif lv 4: writer.add_outline_item(item[title], page, parentlevel_3_ref)这段代码的核心是三个引用变量的维护。每次遇到一级书签就把二级和三级引用清空避免后面的同级节点错误挂到上一个分支的子节点遇到二级书签时把一级引用传进去同时清空三级引用三级和四级同理。有人会问为什么需要清空因为parent参数接收的是对象引用如果不重置下一个同级的二级书签会继续挂在旧的二级引用下面导致书签树分支错乱。这种“引用随层级重置”的方式比试图在 JSON 里显式传parent_id要简单得多也符合大多数书签列表按深度优先排列的特点。参数上offset这里用得比单文件版更灵活可以针对每个书签单独偏移但大多数场景下整个文件一个统一偏移就够了不建议细粒度偏移否则目录和正文页码容易对不上。3.3 命令行入口与日志输出脚本不能只提供函数还得能让非技术同事跑起来。源码里加了个标准的argparse命令行入口参数包括--configJSON 配置路径、--input-dir源文件目录、--output-dir输出目录、--offset全局页码偏移和--dry-run只解析不写入。--dry-run是我强烈建议保留的参数它能先输出每个文件将被写入哪些书签和对应页码不生成任何文件用来验证数据是否正确。批量任务跑之前先 dry-run 一遍能省掉大量反复写入后发现页码不对的麻烦。另一个实用功能是日志。源码里用logging模块输出每个文件的处理状态级别分为INFO开始处理、写入完成和ERROR失败、跳过。日志同时输出到控制台和run.log文件这样任务结束可以直接翻日志排查问题。处理过程里每完成一个文件都打印一行类似[OK] handbook_v2.pdf - 23 bookmarks written一眼就能看出哪些文件成功、哪些失败。批量跑几百个文件时这个形式的日志比大段报错堆栈有用得多。4. 写入书签的进阶操作页码偏移、层级优化与页面裁剪4.1 批量插入封面后的全局偏移处理实际加工 PDF 时最频繁的操作是批量给文档加封面页或版权页。假设你有 50 份 PDF每份需要在最前面插入一张统一样式的封面原书签页码全部加 1如果不处理书签插入封面后书签全乱。正确的处理操作分两步第一步用pypdf的PdfWriter先写一张封面页再合入原文档页面第二步在写书签时给offset传 1让每个书签指向的页码自动后移一位。如果插入的是多页前言偏移量就是插入的总页数。实际操作里封面页的文件可能是一张单独的 PDF也可能是一张图片转成的页面源码里统一封装了个merge_cover(input_pdf, cover_pdf_path, offset_pages1)函数内部实现是先把封面 PDF 的所有页面加入 writer再追加原文档页面。这时候原文档的书签页码必须整体偏移offset_pages。有个细节原文档的元数据信息如作者、标题也会因为写入而丢失如果不做处理输出的 PDF 属性栏会变成空白虽然不是致命问题但给内部归档会造成麻烦。源码里通过writer.add_metadata(reader.metadata)把原元数据搬回来这个小习惯值得保留。4.2 用一级书签做章节重排抽取页面的场景另一个高频场景是把一个大的 PDF 拆成若干小文件并且每个小文件保留原书签的子集。例如从一本 300 页的合集中抽取第 5 章到第 7 章生成一个新 PDF要求新文件里只保留这三个章节对应的书签页码从 1 重新计算。这个场景的麻烦点在于抽取页面后原书签页码全部对不上新页码。需要先计算每个书签对应的页面在原文档中的绝对页码再减去抽取起始页之前的页数得到新页码。计算量不大但容易出错——尤其当抽取范围不是从第 1 页开始时漏掉偏移会导致书签指向错页。def extract_pages_with_bookmarks(src_path, dst_path, page_ranges, bookmark_filterNone, new_start_index0): reader PdfReader(src_path) writer PdfWriter() page_map [] # 新页码 - 原页码 for start, end in page_ranges: for p in range(start, end 1): page_map.append(p - 1) # 转零基 writer.add_page(reader.pages[p - 1]) # 遍历原书签保留在 page_map 内的 offset_pages page_ranges[0][0] - 1 for bm in walk_outline(reader.outline): new_page None if bm.page 0: try: new_page page_map.index(bm.page) except ValueError: new_page None if new_page is not None: writer.add_outline_item(bm.title, new_page, parentNone) with open(dst_path, wb) as f: writer.write(f)上面代码里page_map.index(bm.page)查的是原页码在新文件里的位置时间复杂度 O(n^2)页码量小时足够用如果书签几千条建议改成字典映射。new_start_index参数目前只影响新文件首页是否从 0 开始一般 PDF 阅读器显示页码默认从 1 开始所以这里保持默认即可。需要留意的是这种简单方式生成的新 PDF 书签全部是一级层级结构全部丢失。如果要求保留多级层次就要在遍历原书签时同时记录level和父链关系再按 3.2 节的引用法重建复杂度会高一些但逻辑完全相同。4.3 页码偏移的边界条件测试不管是写书签还是偏移最怕的边界情况有两个书签指向第 1 页和书签指向最后一页。第 1 页转零基后是 0这时add_outline_item能正常处理但如果偏移后页码变成负数例如原书签在第 2 页、偏移 -3那目标页码就是 -2pypdf不会报错但会写入一个无效目标阅读器表现各不相同。所以批量处理前应当把所有目标的页码做一次边界裁剪小于 0 的设为 0大于总页数的设为最后一页。源码里写了个sanitize_page_number函数统一做这个限制避免生成“看起来成功、实际上书签全废”的文件。参数边界速查表场景页码计算公式注意点单文件加封面原页码 封面页数偏移量在所有书签上统一加抽取页面原页码 - 抽取起始页 1起始页是一基页码计算前先减一合并多份 PDF当前文件书签 之前所有文件页数每份文件偏移量不同需逐文件记录删除中间章节大于删除范围的页码减去删除页数删除页之后的书签整体前移调整页序用原页码到新页码的映射表映射表要包含所有保留页面这张表是我处理真实文件时总结的建议读者在自己的工具脚本里把每种偏移单独写成一个函数不要混在一个函数里加不同偏移。混在一起是书签处理最常见的翻车原因尤其当一份 PDF 要同时做插封面和删章节时先后顺序不同结果也不同必须按“先增后删”或“先删后增”制定统一流程。5. 避坑指南PDF 书签处理常见的六个大坑5.1 书签层级错乱二级书签挂到了错误的上级现象写入后打开 PDF发现某几个二级书签没有出现在预期的一级章节下面而是跑到了相邻的一级书签底下。原因3.2 节里提到的引用未重置。循环里遇到同级节点时上一次的level_2_ref还在被继续复用导致后一个二级书签挂到了前一个二级书签的父节点下。这个问题的隐蔽性在于只要跳过分组边界看起来就正常遇到连续多个二级书签时才整个乱掉。解决在循环里每次进入一级书签时强制清空下级引用level_2_ref None、level_3_ref None。同时建议在写入完整个列表后调用writer.outline再读一遍做自检把实际书签层级打印出来对比 JSON 里的预期层级。这套源码里加了--verify参数写完自动重新读取输出文件的书签并与输入列表做对比不一致就报错。5.2 页码偏移方向搞反书签全指向错页现象加封面后书签全部指向封面之前的页面或者指向封面本身正文的章节全乱。原因偏移方向理解错。插入页面后原文档第 N 页变成了新文档第 N offset 页偏移量应该是正数。但很多人在计算时习惯性用了“新页码 原页码 - offset”正好弄反。第二个坑是零基和一基混用add_outline_item要求零基JSON 里存了一基两个数直接相加结果偏差 1 页。解决统一约定JSON 输入一律一基页码调用add_outline_item前先减一偏移量最后叠加。然后在 dry-run 模式下打印前几个书签的旧页码和新页码人为核对一下计算公式。我一般会取第 1 章和最后一章两个书签验证能覆盖首尾边界。5.3 读取书签时抛异常整个程序中断现象处理到某个 PDF 时get_destination_page_number报KeyError或AttributeError脚本终止后面的文件全部没处理。原因该文件的书签目的地是命名目的地或外部 URI没有直接的页面引用。还有一些 PDF 的书签顶层节点是空列表reader.outline返回[]但不为空遍历时类型判断不够严格也会出错。解决遍历时必须对每个节点做isinstance(outline_elem, list)判断并在取页码时整体包一层try-except。源码里读书签函数把异常统一抛给上层由批量任务捕获后记录错误并继续下一个文件。不要把异常吞掉但不记录否则排查时完全不知道哪个文件出了问题。5.4 写入后书签图标是灰色点击无响应现象生成的 PDF 用阅读器打开书签能显示但点击后页面不动或者书签文字呈灰色不可点。原因目标页码越界。add_outline_item传入的页码大于总页数或小于 0 时阅读器无法定位到有效页面表现为灰色或点击无效。这个现象在合并且原书签为新文件时最容易出现——原 PDF 有 200 页抽取后新文件只有 30 页而书签页码还是 50。解决写书签前用len(writer.pages)获取实际页数对所有目标页码做min(page_number, page_count - 1)和max(page_number, 0)的裁剪。不要相信输入数据的“绝对正确”任何来源的书签数据都可能在边界上越界。5.5 批量写入后文件体积暴涨性能反而下降现象一百份 PDF 处理完后每份体积从原来 3MB 涨到 10MB 以上。原因PdfWriter在写入时默认重新编码所有页面内容尤其是含大量图片的扫描版 PDF重编码会膨胀。部分版本的pypdf还存在写回时保留冗余对象的问题导致文件变大。解决处理前先判断是否必须用PdfWriter。如果只是单纯加书签不改页面内容更轻量的方案是直接操作原有 PDF 的对象树只更新大纲字典并保留原有交叉引用表。但这实现复杂度高。务实做法是接受体积膨胀或先用pdfcompression之类工具压缩后再写入。源码里的写入函数增加了optimize_mode和compress参数在writer.write前设置writer.compress True能缓解一部分体积问题。5.6 书签名包含特殊字符生成后乱码或截断现象书签名里含有中文引号、/、()等字符时写入后书名显示异常个别阅读器直接显示空标题。原因PDF 大纲标题需要转义并按照 PDF 文本编码规范处理。中文标题必须使用UTF-16BE或PDFDocEncoding但很多手写脚本直接把 Unicode 字符串塞给add_outline_item某些字符集不完整时输出会损坏。解决在使用pypdf时add_outline_item内部会处理编码但前提是传入 Python 原生str不要自己手动编码成 bytes。另外书名中如果含有/需要转义为\/否则会被解析器当作路径分隔符。源码里加了个sanitize_title函数替换掉/、\、()等有特殊含义的字符保证兼容常见阅读器。6. 验证与日常习惯把书签工具焊进工作流这套源码最值得长期用的地方是它把“读取-计算-写入-校验”串成了一条完整链路。但代码写得好不如跑得稳真正上手后我建议固定一套验证流程先用--dry-run生成日志核对页码和层级然后拿一个只有两三页的小 PDF 做真实写入用阅读器打开看看书签是否可点、点击位置是否正确最后再跑全量。这样三步下来即使书签数据有错也能在最小范围内发现不用等处理完一百个文件才后悔。我现在的日常习惯是任何一批 PDF 需要加书签先把 JSON 配置文件写成和书籍目录完全一致的树形结构层级缩进必须肉眼可见地对应章节然后跑 dry-run 检查每个书签的页码是否递增、是否有跳变。页码跳变通常意味着数据出错比如第 4 章页码 32第 5 章页码 29这明显不合理。再接下来我会随机抽三个不同位置的书签——开头、中间、末尾——打开输出文件实际点一遍确认阅读器定位准确这比写一百行测试代码都管用。还有个细节写书签前我总会先跑一次reader.outline看原 PDF 是否已有书签如果已有且质量还不错我会先备份一份旧书签数据再覆盖防止新书签把原来的目录信息彻底冲掉后悔药得自己留好。使用这套源码时版本兼容性是最容易翻车的地方。老代码里PyPDF2和pypdf的 API 差异很大addOutlineItem和add_outline_item的命名变化、PdfFileReader和PdfReader的类名变化都会导致脚本直接报错。我的建议是锁定pypdf3.0,6.0这个区间5.x 版本的 API 基本稳定后续升级前先跑一遍现有测试集再替换。另外PDF 书签的页码规范在不同阅读器里表现不完全一致Adobe Acrobat 对零基页码的处理和 Chrome 内置阅读器不同批量输出后优先用和最终用户一致的工具验证而不是只看代码逻辑。希望这套源码和避坑经验能帮你省下不少手工整理 PDF 目录的时间。本文还有配套的精品资源点击获取