我太懂这种明明代码能生成新PDF，甚至大纲已经存进文件里，但Mac Preview就是不显示的挫败感了！苹果的PDF文档确实写得有点绕，尤其是大纲对象的底层结构要求，稍微没注意就踩坑。下面我用Python的两个常用库给你做清晰示例，帮你解决问题。

核心问题排查 #

你遇到的情况大概率是大纲的层级结构或根节点设置不符合PDF规范——Preview对PDF标准的兼容性很严格，哪怕底层数据存在，只要结构有一点问题就不会渲染出来。比如直接把自定义的Outline对象当根节点，可能没正确关联到PDF文档的Catalog（目录字典）里，或者缺少了父/子项的引用关系。

方法一：用PyMuPDF（fitz）快速实现（推荐） #

PyMuPDF是处理PDF最省心的库之一，它的大纲API封装得很友好，自动帮你处理底层的PDF结构细节，生成的大纲几乎100%能被Preview识别。

import fitz  # 先安装：pip install pymupdf

# 打开原始PDF文件
doc = fitz.open("你的输入文件.pdf")

# 创建大纲结构，注意页码是0-based（即第1页对应索引0）
# 先创建根大纲项
root_outline = doc.add_outline("目录", 0)  # 根标题跳转到第1页

# 添加一级子项
chapter1 = doc.add_outline("第一章 入门指南", 1, parent=root_outline)  # 跳转到第2页
# 添加二级子项
doc.add_outline("1.1 基本概念", 2, parent=chapter1)  # 跳转到第3页
doc.add_outline("1.2 环境搭建", 4, parent=chapter1)

# 再添加另一个一级项
doc.add_outline("第二章 进阶技巧", 6, parent=root_outline)  # 跳转到第7页

# 保存带大纲的新PDF
doc.save("带大纲的输出文件.pdf")
doc.close()

代码说明 #

• add_outline方法自动帮你维护大纲的层级关系（通过parent参数），以及关联到PDF的Catalog字典，完全符合规范。
• 页码参数是0-based，如果用1-based会导致跳转错误，甚至Preview不识别大纲。

方法二：用PyPDF2实现（适合需要精细控制的场景） #

如果你坚持用PyPDF2，要注意必须通过add_outline_item方法来创建大纲，而不是手动构造Outline对象——它会自动处理根节点的关联和层级引用。

from PyPDF2 import PdfWriter, PdfReader

# 读取原始PDF
reader = PdfReader("你的输入文件.pdf")
writer = PdfWriter()

# 先把所有页面复制到Writer对象
for page in reader.pages:
    writer.add_page(page)

# 创建大纲结构
root_item = writer.add_outline_item("目录", 0)  # 根项，跳转到第1页（0-based）
# 添加一级子项
chapter1 = writer.add_outline_item("第一章 入门指南", 1, parent=root_item)
# 添加二级子项
writer.add_outline_item("1.1 基本概念", 2, parent=chapter1)
writer.add_outline_item("1.2 环境搭建", 4, parent=chapter1)
# 添加另一组一级项
writer.add_outline_item("第二章 进阶技巧", 6, parent=root_item)

# 保存文件
with open("带大纲的输出文件_pypdf2.pdf", "wb") as output_file:
    writer.write(output_file)

为什么之前的代码无效？ #

你之前直接把myOutline作为根对象使用，可能没有将它正确关联到writer的outline_root属性上。PyPDF2的add_outline_item会自动完成这一步，确保大纲结构被正确注册到PDF的Catalog中，Preview才能读取到。

验证大纲是否存在 #

如果你的大纲已经保存到文件但Preview看不到，可以用下面的代码验证大纲是否真的存在：

import fitz
doc = fitz.open("你生成的PDF文件.pdf")
# 遍历所有大纲项
def print_outline(item, indent=0):
    print(f"{'  '*indent}{item['title']} -> 第{item['page']+1}页")
    if item.get("children"):
        for child in item["children"]:
            print_outline(child, indent+1)

if doc.outline:
    print_outline(doc.outline)
else:
    print("文档中没有大纲")

如果能打印出大纲内容，说明结构没问题，试试重启Preview或者右键PDF文件 -> 显示简介 -> 勾选“打开时显示大纲”，有时候是Preview的缓存或设置问题。

内容的提问来源于stack exchange，提问作者benwiggy