PDF批量插入数字序号与二维码：从脚本到工程化解决方案

PDF批量处理Python自动化PyMuPDF

于 2026-08-03 04:11:30 修改

·本内容遵循CC 4.0 BY-SA版权协议

你有没有遇到过这样的场景：手里有一堆PDF文件，可能是合同、报告、证书或者发票，需要给每一页都加上唯一的数字编号，同时还要在特定位置嵌入一个二维码，比如链接到在线版本或者包含唯一标识信息？手动操作的话，打开一个PDF，找到插入位置，输入序号，生成二维码，调整位置，保存……重复几十上百次，不仅枯燥，还极易出错。

这恰恰是很多行政、法务、档案管理甚至开发人员日常工作中真实存在的痛点。表面上看，这只是个简单的“批量插入”任务，但深入下去，你会发现它远不止是调用几个API那么简单。它考验的是你对PDF结构、批量处理逻辑、异常处理以及最终输出可控性的综合理解。很多人尝试用现成工具或写脚本解决，却常常卡在编码问题、位置错乱、性能低下或处理中断上。

今天，我们就以“PDF批量插入数字序号和二维码”这个具体案例为切入点，拆解如何将一个看似简单的需求，打磨成一个稳定、高效且可维护的自动化流程。我们不止步于“能跑通”，更要追求“跑得好”、“跑得稳”。

1. 为什么“批量插入”比想象中复杂：从单次成功到批量稳定

很多人第一次尝试这个需求时，会找到一个能插入文本和图片的PDF库，写一个循环，感觉就完成了。但真正投入使用时，问题才接踵而至。

1.1 单次成功背后的隐形假设

当你成功在单个PDF的某一页插入了一个序号和一个二维码时，你的代码通常建立在几个脆弱的假设之上：

所有PDF结构一致：字体嵌入、页面尺寸、内容布局都相同。
资源路径永远有效：生成二维码的临时图片路径不会冲突或被意外删除。
操作永远成功：每一次写入都不会因为权限、磁盘空间或库的内部错误而失败。
内存和时间无限：处理100个PDF和1000个PDF没有区别。

只要有一个假设被打破，整个批量任务就可能中途崩溃，或者产生难以察觉的错误输出（比如二维码错位到下一页）。因此，批量处理的核心思想，首先是防御性编程和过程可控。

1.2 关键挑战拆解

要实现稳定的批量插入，我们需要系统性地解决以下挑战：

定位精度：如何确保在每个PDF的每一页的固定位置（如页眉、页脚、特定角落）插入内容？绝对坐标和相对坐标如何选择？
内容生成与管理：数字序号如何按规则（连续、按文件分组、重置）生成？二维码的内容（URL、文本）如何与序号或文件信息关联？生成的临时图片文件如何高效管理和清理？
处理性能：同步处理大量文件可能导致内存溢出或耗时过长。是否需要引入队列、分批次或异步处理？
异常与回滚：某个文件损坏导致处理失败，是跳过、记录日志，还是尝试修复？如何处理到一半的程序崩溃？能否支持断点续处理？
输出验证：如何快速验证批量处理后的成百上千个PDF，确保每个文件的每页都正确插入了内容？人工抽查显然不可靠。

理解了这些，我们才能跳出“写一个简单脚本”的思维，转向设计一个健壮的批量处理流程。

2. 核心工具选型与设计思路：不止于库的选择

工欲善其事，必先利其器。选择合适的基础库至关重要，但更重要的是设计思路。

2.1 PDF处理库选型考量

Python生态中有多个PDF处理库，选择时需权衡：

库名称	核心优势	主要考虑点	适合场景
PyPDF2 / pypdf	纯Python，轻量，读写基础操作。	功能相对基础，复杂布局和字体处理可能较弱。	快速原型，处理结构简单、标准的PDF。
ReportLab	强大的PDF生成能力，可精确控制每个元素。	主要用于生成PDF，对修改现有PDF支持较弱。	需要从头生成带序号和二维码的PDF。
pdfrw	擅长读取、合并、拆分，修改元数据。	直接添加新内容（如图片）的支持不如前者直观。	以PDF重组、分析为主，插入为辅的场景。
PyMuPDF (fitz)	功能极其强大，渲染精度高，速度快。	API相对底层，需要更多代码处理细节；安装依赖稍复杂。	高性能、高精度的复杂PDF处理，包括渲染、OCR、高级编辑。

对于“批量插入”这种需要精确定位和可靠性的任务，PyMuPDF通常是更稳妥的选择，因为它能提供更接近底层的控制。而如果需求是“根据数据批量生成全新PDF”，ReportLab则是利器。

注意：库的版本兼容性很重要。特别是Python 3.x的各个子版本，建议在虚拟环境中明确版本号，避免因版本升级导致API变化。

2.2 二维码生成库选择

生成二维码图片通常很简单：

qrcode：最常用，简单易用，生成PNG图像。
segno：另一个不错的选择，功能丰富。选择哪一个差异不大，都能很好地与PDF插入流程集成。

2.3 整体流程设计框架

一个健壮的批量插入流程，应该遵循“准备 -> 处理 -> 验证 -> 清理”的管道模式。下面是一个可参考的设计框架：

TEXT

1. 初始化与配置加载

├── 加载配置（如序号起始值、二维码内容模板、插入位置坐标）

└── 初始化日志系统（记录进度、错误）

2. 预处理与任务编排

├── 扫描源目录，获取待处理PDF文件列表

├── 根据规则（如文件名排序）确定处理顺序

└── 可选：将大任务列表拆分为多个批次，控制内存

3. 单文件处理核心循环 (对列表中的每个PDF)

├── 3.1 打开并验证PDF

├── 3.2 遍历每一页

│ ├── 计算当前页的序号

│ ├── 根据序号生成二维码内容，并创建二维码图片

│ ├── 在指定位置插入序号文本

│ └── 在指定位置插入二维码图片

├── 3.3 保存处理后的PDF到输出目录（使用新文件名，避免覆盖）

└── 3.4 记录成功，清理本文件生成的临时图片

4. 异常处理与恢复

├── 使用 try...except 捕获处理单个文件时的异常

├── 记录失败文件信息及错误原因

└── 跳过失败文件，继续处理下一个（或根据策略停止）

5. 后处理与验证

├── 生成处理报告（成功、失败列表）

└── 可选：抽样打开输出PDF进行自动化检查（如检查特定区域像素）

6. 资源清理

└── 删除所有临时中间文件

这个框架将“插入”这个动作，嵌入到一个受控的流程中，每个环节都有明确的输入输出和错误处理边界。

3. 实战代码拆解：精度、性能与容错

让我们以 PyMuPDF 和 qrcode 库为例，深入代码细节。假设需求是：在每个PDF的每一页右下角插入“第X页”的文本，并在其上方插入一个包含“DocID: 文件名_PageX”信息的二维码。

3.1 环境准备与依赖安装

首先，确保安装必要的库。建议使用 requirements.txt 管理。

BASH

# requirements.txt

PyMuPDF>=1.23.0

qrcode[pil]>=7.0

Pillow>=10.0 # qrcode 依赖的图片处理库

3.2 核心插入函数详解

以下是一个包含基本错误处理和日志记录的核心函数：

PYTHON

import fitz # PyMuPDF

import qrcode

import os

import logging

from PIL import Image

def insert_serial_and_qr_to_pdf(input_pdf_path, output_pdf_path, start_serial=1, qr_content_template="DocID: {filename}_Page{page_num}"):

"""

在PDF每一页插入序号和二维码。

Args:

input_pdf_path: 输入PDF路径

output_pdf_path: 输出PDF路径

start_serial: 起始页码（通常从1开始，但可自定义）

qr_content_template: 二维码内容模板，可用{filename}和{page_num}占位符

"""

log_prefix = f"[处理文件: {os.path.basename(input_pdf_path)}]"

logging.info(f"{log_prefix} 开始处理。")

temp_qr_images = [] # 用于记录临时文件，最后清理

try:

# 1. 打开PDF文档

doc = fitz.open(input_pdf_path)

filename = os.path.splitext(os.path.basename(input_pdf_path))[0]

# 2. 遍历每一页

for page_num in range(len(doc)):

page = doc[page_num]

# 计算当前页的绝对序号（跨文件连续）

current_serial = start_serial + page_num

# 3. 生成二维码

qr_content = qr_content_template.format(filename=filename, page_num=page_num+1)

qr_img = qrcode.make(qr_content)

# 保存为临时文件。使用唯一名称避免多进程/线程冲突。

temp_qr_path = f"temp_qr_{filename}_{page_num+1}.png"

qr_img.save(temp_qr_path)

temp_qr_images.append(temp_qr_path)

# 4. 定义插入位置（以右下角为例）

# 获取页面矩形

page_rect = page.rect

margin = 50 # 距离边界的距离，单位是点（point）

text_height = 20 # 预估文本高度

# 二维码位置：右下角，距离右边界和下边界 margin

qr_width, qr_height = 80, 80 # 二维码显示尺寸

qr_x1 = page_rect.width - margin - qr_width

qr_y1 = page_rect.height - margin - qr_height - text_height - 10 # 在文本上方留10点间距

qr_rect = fitz.Rect(qr_x1, qr_y1, qr_x1 + qr_width, qr_y1 + qr_height)

# 文本位置：二维码正下方

text_x = qr_x1

text_y = qr_y1 + qr_height + 5

text_rect = fitz.Rect(text_x, text_y, page_rect.width - margin, text_y + text_height)

# 5. 插入二维码图片

page.insert_image(qr_rect, filename=temp_qr_path)

# 6. 插入序号文本

# 使用一个简单的文本插入，可以更复杂地设置字体、颜色等

text = f"第 {current_serial} 页"

# 创建一个文本对象（Annotation）或直接绘制

# 这里使用`insert_textbox`，它会在指定矩形内尝试填充文本

# 对于简单文本，`insert_text` 指定坐标更直接

page.insert_text(

(text_x, text_y + text_height - 5), # 文本插入点（左下角坐标）

text,

fontsize=12,

fontname="helv", # 使用标准字体，确保存在

color=(0, 0, 0) # 黑色

)

logging.debug(f"{log_prefix} 第{page_num+1}页处理完成，序号{current_serial}，二维码内容‘{qr_content}’")

# 7. 保存文档

doc.save(output_pdf_path)

logging.info(f"{log_prefix} 处理成功，已保存至 {output_pdf_path}")

except Exception as e:

logging.error(f"{log_prefix} 处理失败，错误信息: {e}", exc_info=True)

raise # 可以选择重新抛出，或返回False

finally:

# 8. 无论如何，尝试清理本文件产生的临时图片

for temp_img in temp_qr_images:

try:

os.remove(temp_img)

except OSError:

pass # 忽略清理错误

logging.debug(f"{log_prefix} 临时文件清理完成。")

if 'doc' in locals():

doc.close()

3.3 批量处理与流程控制

有了单文件处理函数，批量处理就是组织循环和目录。这里展示一个更健壮的批量处理器：

PYTHON

import glob

import time

from pathlib import Path

def batch_process_pdfs(input_dir, output_dir, start_serial=1):

"""

批量处理目录下的所有PDF文件。

"""

input_dir = Path(input_dir)

output_dir = Path(output_dir)

output_dir.mkdir(parents=True, exist_ok=True)

# 获取所有PDF文件，可按需排序

pdf_files = list(input_dir.glob("*.pdf"))

# 或者使用 sorted(pdf_files, key=lambda x: x.name) 按文件名排序

if not pdf_files:

logging.warning(f"输入目录 {input_dir} 中未找到PDF文件。")

return

total_files = len(pdf_files)

logging.info(f"开始批量处理，共 {total_files} 个文件。")

success_count = 0

failed_files = []

current_serial = start_serial

for idx, pdf_file in enumerate(pdf_files, 1):

logging.info(f"进度: {idx}/{total_files} - 正在处理 {pdf_file.name}")

output_file = output_dir / f"processed_{pdf_file.name}"

try:

# 调用单文件处理函数

insert_serial_and_qr_to_pdf(

str(pdf_file),

str(output_file),

start_serial=current_serial,

qr_content_template="ID:{filename}_P{page_num}"

)

# 更新序号：下一个文件的起始序号 = 当前文件起始序号 + 当前文件页数

# 为了获取页数，需要打开文件（这里为了效率，可以在处理函数中返回页数，或再打开一次）

# 简化处理：假设我们知道上一个文件处理成功，序号已递增。更严谨的做法是让处理函数返回最终序号。

# 这里我们采用另一种策略：在批量循环外维护一个全局计数器，每处理一页就递增。

# 但我们的函数内部是按页计算的，所以批量调用时，需要让函数知道“全局”起始点。

# 修改思路：将`start_serial`参数改为“本文件第一页的序号”，并在函数内部逐页递增。

# 因此，我们需要在批量循环中累加页数。让我们调整一下：

# 先打开文件获取页数（会有额外开销，但保证了准确性）

with fitz.open(str(pdf_file)) as temp_doc:

num_pages = len(temp_doc)

current_serial += num_pages

success_count += 1

except Exception as e:

logging.error(f"文件 {pdf_file.name} 处理失败，已跳过。错误: {e}")

failed_files.append((pdf_file.name, str(e)))

# 失败时，序号不应该递增，因为该文件未被成功处理

# 但为了简单，这里我们选择继续递增，否则后续文件序号会错乱。更好的做法是使用独立的文件ID。

# 对于严格的连续页码，失败文件需要被排除在序列外。这取决于业务需求。

# 此处为演示，失败后序号依然递增，假设该文件被“跳过”但占位。

with fitz.open(str(pdf_file)) as temp_doc:

current_serial += len(temp_doc)

# 生成报告

logging.info("="*50)

logging.info(f"批量处理完成。")

logging.info(f"成功: {success_count}/{total_files}")

if failed_files:

logging.info(f"失败: {len(failed_files)}")

for fname, reason in failed_files:

logging.info(f" - {fname}: {reason}")

else:

logging.info("所有文件处理成功。")

关键点：序号连续性的处理需要仔细设计。上面的示例展示了跨文件连续编号的一种方式，但需要权衡打开文件两次的性能损耗。如果文件数量巨大，可以考虑将“获取页数”作为一个独立的预处理步骤，或者接受序号可能在失败文件处不连续。

4. 从能用到好用：性能优化与工程化考量

当文件量从几十个上升到成千上万个时，一些之前忽略的问题就会凸显。

4.1 性能瓶颈分析与优化

I/O操作：频繁的图片保存（qr_img.save）和删除是主要瓶颈。可以考虑：
- 内存图片流：将二维码图片保存在内存中（如 BytesIO），然后直接传递给 PyMuPDF。PyMuPDF 的 insert_image 支持 stream 参数。
PYTHON

import io

# 在循环内

qr_img = qrcode.make(qr_content)

img_byte_arr = io.BytesIO()

qr_img.save(img_byte_arr, format='PNG')

img_byte_arr.seek(0)

# 插入时使用 stream

page.insert_image(qr_rect, stream=img_byte_arr.getvalue())

# 无需保存临时文件，也无需清理
PDF保存：每处理一个文件就保存一次。如果允许，可以考虑将所有修改缓存在内存，最后一次性写入，但这会占用大量内存。通常，按文件处理是平衡点。
并行处理：如果处理是CPU密集型（如图像渲染）或I/O等待时间长，可以考虑使用多进程（multiprocessing）或异步IO。但要注意：
- PDF库和二维码生成库是否线程安全。
- 并行写文件到同一目录可能产生冲突，需要为每个进程/线程分配独立的输出文件名或子目录。
- 日志记录需要改为线程/进程安全的方式。

4.2 可配置化与可维护性

将硬编码的参数提取到配置文件（如JSON、YAML或.env文件）中，提高灵活性。

JSON

// config.json

{

"input_dir": "./source_pdfs",

"output_dir": "./output_pdfs",

"start_number": 1001,

"qr": {

"size": 80,

"content_template": "https://archive.example.com/doc/{file_id}/page/{page}",

"error_correction": "M"

"text": {

"font": "helv",

"size": 11,

"color": [0.2, 0.2, 0.2],

"position": "footer_right"

"batch_size": 50,

"log_level": "INFO"

}

4.3 更健壮的验证机制

人工抽查不可靠，可以编写简单的自动化检查脚本，例如：

使用PyMuPDF提取特定区域的文本，检查是否包含预期序号。
使用二维码解码库（如 pyzbar）读取插入的二维码，验证内容是否正确。
检查输出文件的数量和大小是否在合理范围内。

4.4 错误处理与日志的进阶

分级日志：区分DEBUG（详细步骤）、INFO（进度）、WARNING（可恢复问题）、ERROR（失败）。
结构化日志：便于后续用日志分析工具处理。
告警机制：当失败率超过阈值时，发送邮件或消息通知。
状态持久化：记录处理进度，支持程序中断后从断点恢复。

5. 边界思考：什么情况下这个方案会失效？

没有万能的方案。在以下场景中，上述方法可能需要调整甚至重选方案：

PDF是扫描件（图片型PDF）：PyMuPDF可以插入内容，但定位可能基于图像坐标。如果需要基于OCR文字定位，则需要集成OCR引擎（如Tesseract），复杂度剧增。
PDF有复杂的表单或图层：插入的内容可能会被原有内容遮挡，或破坏表单功能。需要更深入地理解PDF的图层顺序（Optional Content Groups）。
对字体有严格要求：如果要求使用特定字体（如公司LOGO字体），必须确保该字体已嵌入或系统可用，并在代码中明确指定。
海量文件（百万级）：此时单机脚本可能达到极限。需要考虑分布式任务队列（如Celery + Redis）、对象存储（如S3/MinIO）和更强大的批处理框架。
实时性要求高：需要提供API服务，接收PDF流，实时处理并返回。这时要考虑服务化、异步响应和负载均衡。

“PDF批量插入数字序号和二维码”这个案例，就像一把钥匙，打开的是自动化文档处理的大门。它的价值不在于插入动作本身，而在于展示了如何将一个重复、易错的手工操作，抽象成一个定义清晰、输入输出明确、具备容错和监控能力的自动化流程。当你掌握了这套从需求分析、工具选型、流程设计、代码实现到性能优化和边界确认的方法论后，面对“批量加水印”、“批量合并”、“批量提取信息”等类似需求时，你将不再是从零开始，而是有了一个可复用、可演进的解决框架。真正的效率提升，来自于把一次性的脚本，变成可长期服役的工程化解决方案。