本教程详细介绍了如何使用Python的PyMuPDF（fitz）库，高效地批量处理位于多层文件夹中的PDF文件。核心内容包括遍历指定目录下的所有PDF文件，将一个或多个预设的PDF页面追加到现有PDF的末尾，或精确插入到指定位置。教程提供了清晰的示例代码，并强调了内存处理、性能优化及注意事项，帮助用户在服务器环境下实现PDF的自动化合并与管理。

引言

在日常工作中，我们经常会遇到需要对大量PDF文件进行批量操作的场景，例如为所有报告统一添加一个免责声明页，或者在文档开头插入封面页。当这些PDF文件分散在多个层级的文件夹中时，手动操作变得异常繁琐且低效。本教程旨在提供一个基于Python的高效解决方案，利用PyMuPDF库实现对指定目录下所有PDF文件的自动化页面追加与插入，尤其适用于需要定期生成和处理大量PDF文件的自动化流程。

核心工具：PyMuPDF (fitz)

PyMuPDF是一个功能强大且高效的Python库，用于处理PDF文档。它提供了丰富的功能，包括PDF的读取、写入、编辑、渲染等。其底层基于MuPDF库，性能卓越，尤其适合处理大量文件或在资源受限的服务器环境下运行。

在使用之前，请确保已安装PyMuPDF：

pip install PyMuPDF

批量追加PDF页面

本节将演示如何遍历指定根目录及其所有子目录下的PDF文件，并将一个固定的PDF页面追加到每个找到的PDF文件的末尾。

立即学习“Python免费学习笔记（深入）”；

1. 遍历文件与读取PDF

首先，我们需要一个机制来发现所有目标PDF文件。Python的os.walk函数是遍历目录树的理想选择。然后，为了提高效率和稳定性，我们将PDF文件内容读取到内存中进行处理，而不是直接通过文件路径打开。

python-script-generator

快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。

下载

假设我们有一个固定的PDF页面 C:\page2.pdf 需要追加到 C:\Folders 及其子目录下的所有PDF文件中。

import fitz  # PyMuPDF库
import os
import pathlib

# 定义目标根目录和要追加的页面路径
target_folder = r"C:\Folders"
page_to_add_path = r"C:\page2.pdf"

# 收集所有PDF文件路径
pdffiles = []
for root, dirs, files in os.walk(target_folder):
    for name in files:
        if name.endswith(".pdf"):
            pdffiles.append(os.path.join(root, name))

# 打开要追加的源PDF页面
# 注意：这里只打开一次源PDF，避免重复IO操作
try:
    src_page_doc = fitz.open(page_to_add_path)
except fitz.FileNotFoundError:
    print(f"错误：未找到源PDF文件 '{page_to_add_path}'。请检查路径。")
    exit()
except Exception as e:
    print(f"打开源PDF文件时发生错误：{e}")
    exit()

# 遍历并处理每个PDF文件
print(f"开始处理 {len(pdffiles)} 个PDF文件...")
for f_path in pdffiles:
    try:
        # 将目标PDF文件内容读取到内存中
        # 这种方式对于在服务器上处理大量小文件特别有效，避免频繁的文件句柄操作
        stream = pathlib.Path(f_path).read_bytes()
        # 从内存中打开PDF文档
        doc = fitz.open("pdf", stream)

        # 将源PDF文档（这里只有一页）追加到当前文档的末尾
        doc.insert_pdf(src_page_doc)

        # 保存修改后的PDF，覆盖原文件
        # ez_save() 方法是一个便捷的保存方式，它会尝试优化文件大小
        doc.ez_save(f_path)
        print(f"成功处理: {f_path}")
    except fitz.EmptyFileError:
        print(f"警告: 文件 {f_path} 是空的或损坏的PDF，已跳过。")
    except Exception as e:
        print(f"处理文件 {f_path} 时发生错误: {e}")
    finally:
        # 确保文档关闭，释放资源
        if 'doc' in locals() and not doc.is_closed:
            doc.close()

# 关闭源PDF文档
if not src_page_doc.is_closed:
    src_page_doc.close()

print("所有PDF文件处理完成。")

代码解析：

• os.walk(target_folder)：递归地遍历 target_folder 下的所有目录和文件。
• name.endswith(".pdf")：筛选出所有PDF文件。
• fitz.open(page_to_add_path)：打开包含要追加页面的PDF文件。
• pathlib.Path(f_path).read_bytes()：将目标PDF文件的全部内容读取为字节流，存入内存。
• fitz.open("pdf", stream)：从内存中的字节流打开PDF文档，这对于处理大量文件非常高效，因为它避免了每次都从磁盘读取和解析整个文件。
• doc.insert_pdf(src_page_doc)：将 src_page_doc 中的所有页面追加到 doc 的末尾。由于 src_page_doc 通常只有一页，所以相当于追加了那一页。
• doc.ez_save(f_path)：将修改后的PDF保存回原路径，覆盖原文件。

批量插入PDF页面（指定位置）

除了追加页面，有时我们还需要将页面插入到PDF的特定位置，例如在第一页之前插入一个封面，或在最后一页之后插入一个版权页。insert_pdf 方法提供了 start_at 参数来实现这一点。

以下示例演示如何在一个PDF文件开头插入 C:\Files\page1.pdf，并在末尾追加 C:\Files\page3.pdf。

import fitz
import os
import pathlib

# 定义目标根目录和要插入的页面路径
target_folder = r"C:\Folders"
page_before_path = r"C:\Files\page1.pdf"
page_after_path = r"C:\Files\page3.pdf"

# 收集所有PDF文件路径
pdffiles = []
for root, dirs, files in os.walk(target_folder):
    for name in files:
        if name.endswith(".pdf"):
            pdffiles.append(os.path.join(root, name))

# 预先打开要插入的源PDF页面
try:
    src1 = fitz.open(page_before_path)
    src3 = fitz.open(page_after_path)
except fitz.FileNotFoundError as e:
    print(f"错误：未找到源PDF文件。请检查路径：{e}")
    exit()
except Exception as e:
    print(f"打开源PDF文件时发生错误：{e}")
    exit()

print(f"开始处理 {len(pdffiles)} 个PDF文件，插入前后页面...")
for f_path in pdffiles:
    try:
        stream = pathlib.Path(f_path).read_bytes()
        doc = fitz.open("pdf", stream)

        # 在文档的第0页（即开头）插入 src1 的所有页面
        doc.insert_pdf(src1, start_at=0)
        # 在文档的末尾追加 src3 的所有页面
        doc.insert_pdf(src3)

        doc.ez_save(f_path)
        print(f"成功处理: {f_path}")
    except fitz.EmptyFileError:
        print(f"警告: 文件 {f_path} 是空的或损坏的PDF，已跳过。")
    except Exception as e:
        print(f"处理文件 {f_path} 时发生错误: {e}")
    finally:
        if 'doc' in locals() and not doc.is_closed:
            doc.close()

# 关闭源PDF文档
if not src1.is_closed:
    src1.close()
if not src3.is_closed:
    src3.close()

print("所有PDF文件处理完成。")

代码解析：

• doc.insert_pdf(src1, start_at=0)：start_at=0 表示将 src1 中的页面插入到当前文档的第一个位置（索引为0），成为新的第一页。
• doc.insert_pdf(src3)：不带 start_at 参数时，默认行为是追加到文档末尾。

注意事项与最佳实践

1. 备份数据： 运行此类脚本前，务必备份您的PDF文件。脚本会直接覆盖原始文件，一旦出错可能导致数据丢失。
2. 错误处理： 生产环境中，应加入更完善的错误处理机制，例如 try-except 块来捕获文件不存在、PDF损坏等异常，并记录错误日志，而不是简单地跳过或退出。
3. 内存管理： 尽管 fitz 在处理内存方面表现优秀，但如果您的源PDF文件非常大，或者需要同时处理的PDF数量极其庞大，仍需留意系统内存使用情况。将PDF读取到内存（read_bytes()）再处理，通常比反复打开文件句柄更高效。
4. 路径处理： 在Windows系统中，文件路径建议使用原始字符串（r"C:\..."）来避免反斜杠 \ 被解释为转义字符。
5. 性能优化： 对于数千甚至上万个PDF文件，脚本的运行时间会较长。可以考虑使用多线程或多进程来并行处理文件，进一步提升效率，但这会增加代码的复杂性。
6. PyMuPDF版本： 确保使用的PyMuPDF版本较新，以获得最新的功能和性能优化。

总结

本教程展示了如何利用Python和PyMuPDF库，以一种高效且灵活的方式，批量管理分散在多层目录下的PDF文件。无论是简单地追加页面，还是在特定位置插入新页面，PyMuPDF都能提供稳定可靠的解决方案。通过自动化这些重复性任务，可以显著提高工作效率，尤其是在需要定期处理大量文档的场景中。记住，在任何自动化文件操作之前，做好数据备份始终是至关重要的一步。