pypdf移除PDF书签调用remove_from_tree报非树项错误

报错由三个问题共同导致：

• 函数参数定义错误：remove_outline_item形参声明为output_path，实际调用时传入的是writer对象，虽然不触发核心报错，但属于逻辑瑕疵。
• 根级书签不支持remove_from_tree()方法：顶层书签（如日志中的"Cover"）直接挂载在PDF的/Outlines根节点下，本身不存在/Parent属性。remove_from_tree()内部会强制校验对象的/Parent引用，找不到对应父节点就会抛出Removed child does not appear to be a tree item异常。你查到的规则中「不在树结构中的对象需要从源列表移除」，针对的就是这类根级书签——它们的父节点是大纲根对象而非普通书签字典，不能用树形节点的删除逻辑，必须直接从所属的outline列表中移除。
• 遍历逻辑缺陷：正序遍历列表时执行删除操作会导致索引偏移，出现漏删项。

方法1：直接修改原有书签颜色（推荐，无需删除重建） #

pypdf本身支持直接修改已有书签的属性，不用先新增蓝色书签再删除黑色书签，效率更高也不会触发删除逻辑的bug。书签颜色存储在书签对象的/C键下，值为三个0-1区间的浮点数对应RGB值，蓝色对应[0.0, 0.0, 1.0]，直接遍历修改即可：

from pypdf import PdfReader, PdfWriter
from pypdf.generic import NameObject, ArrayObject, FloatObject

def set_bookmark_blue(outline_list):
    # 倒序遍历避免索引偏移
    for i in range(len(outline_list)-1, -1, -1):
        item = outline_list[i]
        if isinstance(item, list):
            # 递归处理子层级书签
            set_bookmark_blue(item)
        else:
            # 直接修改书签颜色为蓝色（RGB 0,0,1）
            item[NameObject("/C")] = ArrayObject([
                FloatObject(0.0),
                FloatObject(0.0),
                FloatObject(1.0)
            ])

reader = PdfReader("input.pdf")
writer = PdfWriter(clone_from=reader)
set_bookmark_blue(writer.outline)

with open("output.pdf", "wb") as f:
    writer.write(f)

方法2：删除原有黑色书签后重建 #

如果一定要走「删除黑色旧书签+新增蓝色新书签」的逻辑，需要区分根节点和非根节点做不同处理：根节点直接从所在列表移除，非根节点再调用remove_from_tree()，同时采用倒序遍历避免索引问题：

from pypdf import PdfReader, PdfWriter

def remove_black_bookmarks(outline_list):
    # 倒序遍历，防止删除元素后索引跳变漏删
    for i in range(len(outline_list) - 1, -1, -1):
        item = outline_list[i]
        if isinstance(item, list):
            remove_black_bookmarks(item)
        else:
            if item.color == [0.0, 0.0, 0.0]:
                print(f"Removing bookmark: {item.title}, parent: {item.get('/Parent')}")
                if item.get("/Parent") is None:
                    # 根级书签直接从当前列表移除
                    outline_list.pop(i)
                else:
                    # 非根级书签调用树节点删除方法
                    item.remove_from_tree()

reader = PdfReader("input.pdf")
writer = PdfWriter(clone_from=reader)
remove_black_bookmarks(writer.outline)

# 此处追加新增蓝色书签的自定义逻辑即可

with open("output.pdf", "wb") as f:
    writer.write(f)

• 遍历嵌套列表执行删除、修改操作时必须倒序遍历，否则删除元素后列表长度收缩，后续元素会前移，导致遍历跳过部分条目。
• 禁止对根级书签调用remove_from_tree()：该方法的实现逻辑是通过/Parent属性向上溯源，找到父节点存储子项的列表后执行删除，根级书签无/Parent属性，调用必然报错。
• 优先选择直接修改书签属性的方案：删除后重建书签容易丢失原有书签的跳转定位、页面缩放、层级关联等属性，直接修改颜色属性的稳定性更高。

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