Python自动化批量处理PDF：添加序号与二维码的完整解决方案

PDF批量处理Python自动化二维码生成

于 2026-08-03 04:12:48 修改

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

在日常文档管理和分发工作中，我们常常会遇到这样的场景：需要将一批PDF文件（如合同、报告、证书）分发给不同的接收方，为了便于追踪和管理，需要在每一页的固定位置（如页眉或页脚）插入唯一的数字序号，并添加一个包含特定信息（如文档ID或链接）的二维码。手动操作不仅效率低下，而且极易出错。本文将分享一套基于Python的自动化解决方案，通过整合PyPDF2、reportlab和qrcode等库，实现PDF文件的批量数字序号插入与二维码生成，并提供完整的代码示例和避坑指南，无论是处理几十份还是上千份文档，都能轻松应对。

1. 背景与核心概念

在深入代码之前，我们有必要厘清几个核心概念及其应用价值。

PDF文档处理：PDF（Portable Document Format）是一种与设备无关的文件格式，广泛应用于文档交换。对PDF的编程操作主要包括读取、合并、拆分、添加水印、插入文本或图像等。批量处理的核心在于自动化遍历文件和对每个文件进行结构化修改。

数字序号：这里指的是为每一份PDF文档或每一页赋予的一个唯一标识符，通常是递增的数字。插入序号的目的在于实现文档的序列化，便于物理归档后的快速定位、电子目录的建立以及分发记录的管理。例如，为一批合同文件编号“CONTRACT-001”至“CONTRACT-100”。

二维码（QR Code）：二维码是一种矩阵式二维条码，能够存储大量信息，如文本、URL等。在PDF文档管理中，二维码的典型应用包括：

信息嵌入：将文档编号、关键属性（如客户ID、日期）直接编码进二维码。
快速访问：编码一个指向文档在线存储位置或详情页的URL，实现“扫码即得”。
防伪与验证：结合后端系统，通过扫码验证文档真伪或状态。

批量处理：指通过编写脚本程序，自动对指定目录下的所有PDF文件执行一系列相同的操作。这避免了人工重复劳动，保证了处理规则的一致性，并极大提升了效率。

为什么需要掌握这项技能？ 对于开发人员、运维人员或经常处理文档的办公人员来说，掌握PDF自动化处理能力，意味着能将繁琐、重复的文档后期处理工作转化为一键执行的脚本，是提升工作效率、减少人为错误、实现流程标准化的重要工具。

2. 环境准备与版本说明

本教程基于Python环境，因其拥有丰富且成熟的PDF处理库。请确保你的开发环境已就绪。

操作系统：Windows 10/11, macOS, 或 Linux (如 Ubuntu) 均可。 Python版本：推荐使用 Python 3.8 及以上版本。本文示例代码在 Python 3.9 环境下测试通过。 集成开发环境（IDE）：可使用 VS Code、PyCharm 或任何你熟悉的文本编辑器。

2.1 创建虚拟环境（推荐）

为避免包依赖冲突，建议为项目创建独立的虚拟环境。

BASH

# 在项目根目录下

python -m venv venv

# 激活虚拟环境

# Windows (cmd或PowerShell)

venv\Scripts\activate

# macOS / Linux

source venv/bin/activate

2.2 安装依赖库

我们将使用以下核心库：

PyPDF2：一个纯Python的PDF库，用于读取、拆分、合并PDF文件。这里我们主要用其读取功能。
reportlab：一个功能强大的PDF生成与处理库，用于创建新的PDF页面、绘制文本和图像（二维码）。
qrcode 和 Pillow (PIL)：用于生成二维码图片。qrcode负责编码，Pillow负责图像处理。

通过pip一键安装所有依赖：

BASH

pip install PyPDF2 reportlab qrcode[pil] Pillow

版本说明：安装时无需指定具体版本，pip会自动安装兼容的稳定版。若后续运行出现问题，可尝试固定版本，例如：

BASH

pip install PyPDF2==3.0.1 reportlab==4.0.4 qrcode==7.4.2 Pillow==10.1.0

2.3 示例项目结构

建议按以下结构组织你的项目，使代码清晰易管理：

TEXT

pdf_batch_processor/

├── src/

│ ├── main.py # 主程序入口

│ ├── pdf_processor.py # PDF处理核心逻辑

│ └── qr_generator.py # 二维码生成逻辑

├── input_pdfs/ # 存放待处理的原始PDF文件

├── output_pdfs/ # 存放处理后的PDF文件

├── temp_qr/ # 临时存放生成的二维码图片

├── requirements.txt # 项目依赖列表

└── README.md

你可以先在input_pdfs文件夹中放入几个用于测试的PDF文件。

3. 核心库与原理拆解

在编写完整代码前，我们先理解各个库的关键对象和方法。

3.1 PyPDF2：读取PDF与页面操作

PyPDF2 的 PdfReader 用于读取PDF文件。我们通过它获取原始PDF的每一页。

PYTHON

from PyPDF2 import PdfReader

reader = PdfReader(‘原始文件.pdf‘)

num_pages = len(reader.pages) # 获取总页数

first_page = reader.pages[0] # 获取第一页对象

# 注意：PyPDF2获取的页面对象主要用于提取内容，不能直接用于reportlab绘图。

3.2 reportlab：创建新PDF与绘图

reportlab 是本次任务的主力。我们使用 canvas.Canvas 来创建一个新的PDF页面，并在上面“作画”。

核心概念：

Canvas（画布）：代表一个PDF页面，你可以在上面绘制文本、线条、形状和图像。
坐标系统：原点 (0, 0) 默认在页面左下角。坐标单位是点（point， 1 inch = 72 points）。确定文本或图像位置时，需要精确计算坐标。
drawString(x, y, text)：在指定坐标绘制文本。
drawImage(image_path, x, y, width, height)：在指定位置绘制图像，并指定宽高。

PYTHON

from reportlab.pdfgen import canvas

from reportlab.lib.pagesizes import A4 # 引入标准页面尺寸

# 创建一个A4大小的PDF文件

c = canvas.Canvas(“新页面.pdf“, pagesize=A4)

width, height = A4 # 获取页面的宽和高

# 在距离左下角 (100, 800) 的位置绘制文本

c.drawString(100, height - 100, “文档编号: 2024-001“)

# 在页面右下角绘制一个二维码图片

qr_width, qr_height = 50, 50 # 二维码大小

c.drawImage(“qr_code.png“, width - qr_width - 50, 50, qr_width, qr_height)

c.save() # 保存画布内容到文件

3.3 qrcode：生成二维码图像

qrcode 库非常简单易用。我们生成二维码并保存为图片文件，供 reportlab 调用。

PYTHON

import qrcode

# 创建QRCode对象

qr = qrcode.QRCode(

version=1, # 控制二维码大小（1-40），值越大，存储信息越多，图形越复杂

error_correction=qrcode.constants.ERROR_CORRECT_L, # 容错率 L/M/Q/H

box_size=10, # 每个小格子包含的像素数

border=4, # 二维码与图片边界的距离（格子数）

)

# 添加数据

data = “https://www.example.com/doc/12345“

qr.add_data(data)

qr.make(fit=True)

# 生成图像并保存

img = qr.make_image(fill_color=“black“, back_color=“white“)

img.save(“doc_12345_qr.png“)

关键参数解释：

error_correction：容错等级。即使部分区域损坏，也能正确读取。L级约可恢复7%的数据，H级约30%。对于文档应用，L或M级通常足够。
version：如果fit=True，库会自动选择能容纳数据的最小版本。

4. 完整实战案例：批量插入序号和二维码

现在，我们将上述知识整合，构建一个完整的批量处理器。假设需求是：为input_pdfs目录下的每个PDF文件，在首页右上角添加“编号：[序号]”，并在首页右下角添加一个包含文档编号的二维码。

4.1 创建项目结构与核心模块

首先，创建 qr_generator.py，专门负责二维码生成。

PYTHON

# file: src/qr_generator.py

import qrcode

import os

def generate_qr_code(data: str, save_path: str, box_size=10, border=4):

"""

生成二维码并保存为图片。

参数:

data (str): 要编码到二维码中的数据。

save_path (str): 二维码图片的保存路径（包含文件名）。

box_size (int): 二维码每个小格子的像素大小。

border (int): 二维码边框的格子数。

"""

try:

qr = qrcode.QRCode(

version=1,

error_correction=qrcode.constants.ERROR_CORRECT_L,

box_size=box_size,

border=border,

)

qr.add_data(data)

qr.make(fit=True)

img = qr.make_image(fill_color=“black“, back_color=“white“)

# 确保保存目录存在

os.makedirs(os.path.dirname(save_path), exist_ok=True)

img.save(save_path)

print(f“二维码已生成: {save_path}“)

return save_path

except Exception as e:

print(f“生成二维码失败，数据: {data}, 错误: {e}“)

return None

接下来，创建 pdf_processor.py，包含处理单个PDF和批量处理的逻辑。

PYTHON

# file: src/pdf_processor.py

import os

from PyPDF2 import PdfReader

from reportlab.pdfgen import canvas

from reportlab.lib.pagesizes import A4

from reportlab.lib.units import mm # 引入毫米单位，方便计算

from .qr_generator import generate_qr_code # 导入二维码生成函数

def process_single_pdf(input_pdf_path: str, output_pdf_path: str, serial_number: str, qr_data: str, temp_dir: str = “temp_qr“):

"""

处理单个PDF文件：在首页添加序号和二维码。

参数:

input_pdf_path (str): 原始PDF文件路径。

output_pdf_path (str): 处理后的PDF输出路径。

serial_number (str): 要添加的序号文本。

qr_data (str): 编码到二维码中的数据。

temp_dir (str): 临时存放二维码图片的目录。

"""

# 1. 生成二维码图片

qr_filename = f“qr_{serial_number}.png“

qr_temp_path = os.path.join(temp_dir, qr_filename)

qr_image_path = generate_qr_code(qr_data, qr_temp_path)

if not qr_image_path:

print(f“跳过文件 {input_pdf_path}, 因二维码生成失败。“)

return False

# 2. 读取原始PDF

reader = PdfReader(input_pdf_path)

if len(reader.pages) == 0:

print(f“文件 {input_pdf_path} 无有效页面，跳过。“)

return False

# 获取第一页的尺寸（假设所有页面尺寸一致）

first_page = reader.pages[0]

# 注意：PyPDF2获取的页面尺寸是点（points），我们需要将其转换为与reportlab兼容的尺寸。

# 一个简单的方法是使用A4标准尺寸，或者从页面对象中提取（更复杂）。

# 为简化，本例假设原始PDF为A4大小。若非A4，需要更复杂的尺寸获取逻辑。

page_width, page_height = A4

# 3. 创建新的Canvas，绘制原始第一页内容（通过叠加图像方式）

# 更优方案：使用reportlab的pdfrw库直接插入页面，但为简化，我们采用“先绘制原始PDF为背景图”的思路。

# 注意：此方法会丢失原始PDF的矢量信息和可搜索文本，仅适用于简单文档或作为示例。

# 生产环境建议使用更专业的库如`pdf2image`将PDF页转为图片，再插入。

# 此处为演示核心流程，我们创建一个新页面，仅添加序号和二维码。

# 实际应用中，你可能需要保留原内容。以下代码演示添加元素到空白页。

c = canvas.Canvas(output_pdf_path, pagesize=A4)

# 4. 在首页添加文本序号（右上角）

text_x = page_width - 50 * mm # 距离右边50mm

text_y = page_height - 20 * mm # 距离顶部20mm

c.setFont(“Helvetica“, 12)

c.drawString(text_x, text_y, f“编号: {serial_number}“)

# 5. 在首页添加二维码（右下角）

qr_size = 20 * mm # 二维码大小20mm x 20mm

qr_x = page_width - qr_size - 20 * mm # 距离右边20mm

qr_y = 20 * mm # 距离底部20mm

c.drawImage(qr_image_path, qr_x, qr_y, qr_size, qr_size)

# 6. 保存新页面

c.save()

# 7. （可选）将原始PDF的其他页面追加到新文件后面。

# 这需要更复杂的PDF合并操作，可使用PyPDF2的PdfMerger。

# 本示例专注于首页处理，暂不实现多页追加。

print(f“已处理: {input_pdf_path} -> {output_pdf_path}“)

return True

def batch_process_pdfs(input_dir: str, output_dir: str, start_serial=1, prefix=“DOC-“, qr_data_template=“https://doc.example.com/id/{}“):

"""

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

参数:

input_dir (str): 输入PDF目录。

output_dir (str): 输出PDF目录。

start_serial (int): 起始序号。

prefix (str): 序号前缀。

qr_data_template (str): 二维码数据模板，{}会被替换为完整序号。

"""

if not os.path.exists(input_dir):

print(f“输入目录不存在: {input_dir}“)

return

os.makedirs(output_dir, exist_ok=True)

os.makedirs(“temp_qr“, exist_ok=True)

pdf_files = [f for f in os.listdir(input_dir) if f.lower().endswith(‘.pdf‘)]

pdf_files.sort() # 按文件名排序，保证处理顺序

current_serial = start_serial

for pdf_file in pdf_files:

input_path = os.path.join(input_dir, pdf_file)

# 生成输出文件名，可添加后缀以区分

output_filename = f“processed_{pdf_file}“

output_path = os.path.join(output_dir, output_filename)

full_serial = f“{prefix}{current_serial:03d}“ # 格式化为三位数，如 DOC-001

qr_data = qr_data_template.format(full_serial)

success = process_single_pdf(input_path, output_path, full_serial, qr_data)

if success:

current_serial += 1

print(f“批量处理完成。共处理 {len(pdf_files)} 个文件，序号从 {prefix}{start_serial:03d} 开始。“)

# 清理临时二维码图片（可选）

# import shutil

# shutil.rmtree(‘temp_qr‘)

最后，创建主程序入口 main.py。

PYTHON

# file: src/main.py

import sys

import os

sys.path.append(os.path.dirname(os.path.abspath(__file__)))

from pdf_processor import batch_process_pdfs

if __name__ == “__main__“:

# 配置路径和参数

INPUT_DIR = “../input_pdfs“ # 相对于src目录的路径

OUTPUT_DIR = “../output_pdfs“

START_SERIAL = 1

SERIAL_PREFIX = “CONTRACT-“

QR_DATA_TEMPLATE = “https://company.com/contract/{}“ # {} 会被替换为完整序号

print(“开始批量处理PDF...“)

batch_process_pdfs(

input_dir=INPUT_DIR,

output_dir=OUTPUT_DIR,

start_serial=START_SERIAL,

prefix=SERIAL_PREFIX,

qr_data_template=QR_DATA_TEMPLATE

)

print(“处理完毕。请查看 output_pdfs 目录。“)

4.2 运行与验证

将你的测试PDF文件放入 项目根目录/input_pdfs/ 文件夹。
在项目根目录下，运行主程序：

BASH

python src/main.py
观察控制台输出，应该能看到类似以下信息：

TEXT

开始批量处理PDF...

二维码已生成: temp_qr/qr_CONTRACT-001.png

已处理: ../input_pdfs/合同1.pdf -> ../output_pdfs/processed_合同1.pdf

二维码已生成: temp_qr/qr_CONTRACT-002.png

已处理: ../input_pdfs/合同2.pdf -> ../output_pdfs/processed_合同2.pdf

批量处理完成。共处理 2 个文件，序号从 CONTRACT-001 开始。

处理完毕。请查看 output_pdfs 目录。
打开 output_pdfs 目录下的任意一个处理后的PDF文件，检查首页右上角是否出现了“编号: CONTRACT-001”等文本，右下角是否出现了对应的二维码。用手机扫描二维码，应能跳转到预设的URL（或显示编码的文本）。

4.3 结果说明

运行成功后，output_pdfs 目录下会生成一系列以 processed_ 开头的PDF文件。每个文件的第一页都已被修改，添加了唯一的序列号和对应的二维码。temp_qr 目录下保存了过程中生成的临时二维码图片，处理完成后可以手动删除或让脚本自动清理。

5. 常见问题与排查思路

在实际操作中，你可能会遇到以下问题：

问题现象	常见原因	解决思路
`ModuleNotFoundError: No module named ‘PyPDF2‘`	依赖库未安装或未在正确的虚拟环境中安装。	1. 确认虚拟环境已激活（命令行前有`(venv)`标识）。 2. 运行 `pip list` 检查是否安装了所需库。 3. 重新运行 `pip install -r requirements.txt` 或手动安装。
处理后的PDF只有一页，丢失了原内容	示例代码中为了简化，只创建了新页面绘制序号和二维码，未将原PDF内容合并进去。	这是示例代码的局限性。生产方案需改进： 1. 使用`pdf2image`将原PDF页转为图片，再用`reportlab`将图片作为背景绘制。 2. 使用`pdfrw`库直接读取原PDF页面对象，与`reportlab`生成的页面合并。这是更专业的方法。
二维码或文本位置不正确	`reportlab`的坐标计算错误。原点在左下角，单位是点。	1. 使用 `from reportlab.lib.units import mm, cm, inch` 引入单位转换器，方便计算。 2. 打印 `page_width, page_height` 确认页面尺寸。 3. 通过多次调试，微调 `drawString` 和 `drawImage` 的 `x, y` 坐标参数。
处理大量PDF时内存占用高或速度慢	1. 二维码图片未及时清理。 2. 原PDF文件过大。 3. 循环内重复创建对象。	1. 每处理完一个文件，立即删除其对应的临时二维码图片 (`os.remove`)。 2. 考虑使用流式处理，避免一次性将整个PDF读入内存。 3. 将 `PdfReader` 和 `canvas.Canvas` 的创建放在循环内，处理完及时释放。
生成的二维码无法扫描	1. 二维码尺寸太小。 2. 二维码颜色对比度低。 3. 编码数据过长，超过了所选`version`的容量。	1. 增大 `drawImage` 中的 `width` 和 `height` 参数，或生成二维码时增大 `box_size`。 2. 确保使用 `fill_color=“black“, back_color=“white“` 高对比度组合。 3. 设置 `qr.make(fit=True)` 让库自动选择合适版本，或手动增加 `version` 值。
中文字符显示为乱码	`reportlab` 默认字体不支持中文。	1. 下载中文字体文件（如`.ttf`）。 2. 使用 `reportlab.pdfbase.ttfonts.TTFont` 注册字体。 3. 在 `drawString` 前使用 `c.setFont(“注册的字体名“, size)`。

6. 最佳实践与工程建议

将脚本投入实际项目使用时，请考虑以下建议以提升代码的健壮性、可维护性和性能。

6.1 代码结构优化

配置文件：将输入输出目录、序号规则、二维码模板等参数抽取到独立的配置文件（如config.yaml或config.ini）中，避免硬编码。
日志记录：使用Python内置的logging模块替代print，可以输出不同级别（INFO, WARNING, ERROR）的日志到文件和控制台，便于问题追踪。
异常处理：在batch_process_pdfs和process_single_pdf函数中，使用更精细的try...except块捕获特定异常（如FileNotFoundError, PermissionError），并给出友好的错误提示，避免整个程序因单个文件问题而崩溃。

6.2 功能增强与生产级方案

保留原PDF内容：如前所述，示例代码丢失了原内容。生产环境应采用pdf2image + reportlab或pdfrw + reportlab的方案。以下是pdf2image方案的简要思路：

PYTHON

from pdf2image import convert_from_path

images = convert_from_path(input_pdf_path, first_page=1, last_page=1)

first_page_image = images[0]

image_path = “temp_first_page.png“

first_page_image.save(image_path, ‘PNG‘)

# 然后在canvas上使用c.drawImage绘制这个image_path作为背景，再叠加序号和二维码。
多页处理：遍历reader.pages，对每一页或指定页添加页眉/页脚。注意坐标计算可能每页一致。
动态二维码内容：二维码数据不仅可以包含序号，还可以从文件名、Excel表格、数据库中读取其他信息（如客户姓名、日期）进行组合编码。
性能优化：对于超大批量文件，可以考虑使用concurrent.futures.ThreadPoolExecutor进行多线程处理，但要注意文件IO和GIL限制。更复杂的情况可使用异步IO或任务队列。

6.3 安全与合规性

文件权限：确保脚本运行账户对输入目录有读权限，对输出目录和临时目录有写权限。
临时文件清理：务必在脚本结束时或每个文件处理完成后，清理临时生成的二维码图片，防止磁盘空间被占用。
数据安全：如果二维码编码的是内部URL或敏感信息，确保输出PDF的存储和分发渠道安全，避免信息泄露。
备份原始文件：在脚本开始处理前，可以考虑先将原始PDF复制到备份目录，防止处理出错导致原文件损坏。

6.4 可维护性

单元测试：为generate_qr_code和process_single_pdf等核心函数编写单元测试，确保逻辑正确。
命令行接口（CLI）：使用argparse或click库为脚本添加命令行参数，使其更易于集成到自动化流程或由其他系统调用。

PYTHON

# 示例：python main.py --input ./docs --output ./processed --start 100 --prefix INV

7. 总结与扩展方向

通过本文，我们系统地实现了一个PDF批量插入序号和二维码的Python脚本。你掌握了使用PyPDF2读取PDF、使用qrcode生成二维码、以及使用reportlab绘制PDF页面的核心技能，并了解了从单文件处理到批量操作的完整流程。

关键点回顾：

环境搭建：创建虚拟环境并安装PyPDF2, reportlab, qrcode[pil], Pillow。
核心原理：reportlab的Canvas坐标系统是操作的关键，确定元素位置需要精确计算。
流程拆解：批量处理的核心循环是：遍历文件 -> 生成唯一序号和二维码数据 -> 处理单个文件 -> 保存输出。
问题定位：遇到问题优先检查依赖、坐标计算、文件路径和编码数据。

下一步可以探索：

深入研究reportlab：学习绘制表格、图表、使用样式表（Stylesheet）来制作更复杂的PDF文档。
集成OCR：结合pytesseract等库，先识别PDF中的文本，再根据文本内容决定插入何种二维码或编号。
开发Web服务：使用Flask或FastAPI将本脚本包装成一个REST API，提供Web界面上传PDF并返回处理后的文件。
定时任务：结合cron（Linux）或Task Scheduler（Windows），将脚本设置为定时任务，自动处理特定文件夹下的新增PDF文件。

处理文档自动化是提升工作效率的利器。从这个小项目出发，你可以将其改造成适合自己业务需求的强大工具，例如自动生成带二维码的会议纪要、批量处理扫描件等。动手尝试修改代码中的参数和逻辑，是巩固学习成果的最佳方式。如果在实践中遇到新的问题，欢迎在社区交流探讨。