应优先解析PDF自带大纲（outline），再fallback正则+字体特征识别标题；合并时用pypdf重映射书签页码并维持层级；目录页需手动插入带链接的新页面，注意页码偏移。
pdfplumber 读取 PDF 文本失败，书签标题提取不准怎么办
直接用 pdfplumber 逐页提取文本再匹配标题，极易漏掉无文字的扫描版 PDF，或把页眉页脚、表格内容误判为标题。真正可靠的方式是优先利用 PDF 自带的结构信息——也就是 PyPDF2 或更新的 pypdf 提供的 outline（大纲）解析能力。
实操建议：
- 先尝试用
reader.outline读取原始 PDF 的书签结构（如果存在），它返回的是嵌套的Destination或OutlineItem对象，含标题、目标页码、层级等字段 - 若原始 PDF 没有书签（如纯扫描件），再 fallback 到基于规则的文本识别：比如正则匹配「第[一二三四]章」、「1\. 」、「\d+\s+[\u4e00-\u9fa5]+」这类模式，并结合字体大小、居中/加粗特征（需
pdfplumber配合page.chars分析） - 避免全文模糊搜索“目录”二字定位目录页——很多 PDF 目录是图片或非标准排版，成功率极低
合并时保留原 PDF 书签并重映射页码用 pypdf 最稳
PyPDF2 旧版对书签处理较弱，容易丢失层级或页码偏移错乱；pypdf（v3.0+，PyPDF2 的继任者）的 add_outline_item 和 add_outline_item_to_page 接口更可控，且能自动修正跨文档的页码偏移。
关键步骤：
立即学习“Python免费学习笔记（深入）”；
提示词大师-python版
下载
图片提示词生成器？不止如此。 马甲系统 —— 把脑海中的画面，翻译成AI能理解的专业表达。 用得越多，它越懂你：首次需要多问几句确认方向，用久了几乎一说就懂。 用得越多，它越快：缓存机制让后续对话越来越省。 RAG进化：成功案例持续入库，越跑越聪明。 输入「新手指南」查看完整功能介绍
- 用
PdfReader分别加载每个源 PDF，遍历其outline，用get_destination_page_number()获取原页码 - 每合并一个文件前，记录当前总页数
offset，将原书签页码 +offset得到新位置 - 调用
merger.add_outline_item(title, page_number, parent=parent)逐条重建，注意用parent参数维持缩进层级（首次传None，子项传上一级返回值） - 不推荐用
merger.append()后统一加书签——页码映射易出错，尤其当某 PDF 有非连续页码（如含封面、版权页跳号）
生成动态书签目录页（非嵌入式）要手动写入 PDF 页面
用户常混淆“PDF 内置书签”和“可视化的目录页”。前者是侧边栏可点击的导航树，后者是实际插入的一张 PDF 页面，含文字+超链接。两者可共存，但生成方式完全不同。
若需自动生成带跳转链接的目录页：
- 用
reportlab或fpdf2新建一页 PDF，循环写入标题文字，并用link = canvas.linkRect(...)或pdf.set_link(...)绑定到对应页码 - 链接目标页码必须是最终合并后文档内的绝对页码（从 0 开始），不是原文件页码
- 注意：插入的目录页本身会增加总页数，所以后续所有书签页码要再 +1（如果目录页插在最前面）
- 不要试图用
pypdf把 HTML 渲染成 PDF 目录页——渲染质量差、中文支持弱、链接难控制
命令行批量处理多个 PDF 时路径与编码容易出错
常见报错如 UnicodeDecodeError: 'gbk' codec can't decode byte 或 FileNotFoundError，根本原因不是 Python 代码，而是 Windows 下默认 shell 编码和路径空格/中文处理不当。
安全做法：
- 输入路径统一用
pathlib.Path处理，例如list(Path(".").glob("*.pdf"))，避免字符串拼接 - 文件名含中文时，确保终端（CMD/PowerShell）已执行
chcp 65001切换 UTF-8，或直接用 VS Code 终端（默认 UTF-8） - 不要用
os.system("pdftk ...")调外部工具——pdftk已停止维护，且不支持新 PDF 标准，书签全丢 - 调试阶段加一句
print(f"Adding {pdf_path.name} → offset {offset}")，确认文件顺序和页码累加逻辑是否符合预期
