PDF批量生成这个需求估计每一个跟文档打交道的开发者和办公人员都遇到过。合同要一份份套模板、证书要一条条填信息、报表要一次次导出手动操作不仅慢还容易在复制粘贴时把数据弄错。我一直在做文档自动化相关的工作索性就自己写了一个轻量级的生成工具也就是这个PDF Editor v0.1.3。这个版本的核心定位很明确把数据——模板——PDF文件这条链路完全打通只需要维护好一张表和一个页面模板就能批量产出几百份格式统一的PDF文档。这篇文章我打算把这套工具从设计思路到具体实现、再到三个版本迭代踩过的坑完完整整梳理一遍适合正在做文档自动化的开发、运维以及日常需要大量处理PDF的办公人员参考。1. 为什么需要自研PDF批量生成工具选题背景与需求拆解1.1 工作中真实的批量PDF生成场景拿我自己遇到的情况来说最典型的是月度结算报告。每月底我需要为几十个渠道方各自生成一份PDF对账单里面有固定格式的公司抬头、渠道名称、结算周期、订单量明细、结算金额、备注栏最后还要生成一个统一的文件命名方便归档。最早我是用Word做好模板然后逐条替换内容再另存为PDF一个渠道至少要花两三分钟几十份下来一上午就没了。更麻烦的是一旦某个数字要调整又得全部重新来一遍。类似这样的场景远不止对账单。常见的还有电子证书批量制作、产品规格书批量导出、批量邀请函或通知函、数据库巡检报告的定时生成以及企业内部的采购单、入库单打印。这类任务的共同特征是页面版式固定只有局部数据变化数据源通常是Excel表、CSV文件或者业务系统里的数据库输出要求是规范、可归档的PDF格式。1.2 常见的临时方案为什么撑不住很多人遇到这个问题第一反应是找现成工具。市面上确实有不少PDF处理软件它们大多支持PDF合并、拆分、压缩、格式转换听起来很接近需求。但真拿去批量生成就会遇到几个绕不过去的坎第一数据绑定能力几乎为零。工具类软件擅长处理已经存在的PDF文件但你要让它根据Excel每一行生成一个新PDF绝大多数工具做不到或者做得很笨重。第二样式控制不够精细。批量生成要求每份文件的字体、间距、对齐方式完全一致很多傻瓜工具导出来页面元素错位尤其是中文排版体验非常差。第三在线工具存在数据安全隐患。把客户信息、结算金额传到第三方网站去生成文件先不谈效率数据这一关就过不去。第四无法嵌入自动化链路。生成完文件之后你可能还要自动命名、自动归档、自动发邮件手动工具根本接不上这些流程。1.3 v0.1.3的产品定位与技术边界所以我自己动手写了这个工具。v0.1.3这个版本我给它定了一个非常清晰的能力边界输入是结构化数据输出是一批版式一致的PDF文件中间过程靠代码控制不引入重型平台依赖。它不做PDF任意的自由编辑不做扫描件的文字识别也不做复杂的可视化排版设计这些是另外一些专业工具擅长的领域。我做的是把批量生成这一件事做到足够顺手让一个完全不懂代码的同事只要会填Excel表也能跑出成品文件。从架构上看这个版本把生成流程拆成了四段数据读取、模板渲染、文件产出、结果校验。数据读取解决Excel里的数据如何干净地进入内存的问题模板渲染解决同一套样式如何套到不同数据上的问题文件产出解决命名、分目录、性能控制的问题结果校验解决生成出来的文件有没有缺页、缺字、打不开的问题。把这四段拆清楚后面无论换数据源还是换输出形式都不用推倒重来。2. 核心技术选型与架构设计解析2.1 四条技术路线的对比与取舍在真正动手之前我把批量生成PDF的主流技术路线都考察了一遍。当时的备选方案有四个技术路线代表工具/库优点缺点适合场景PDF库直接绘制ReportLab、FPDF2精细控制PDF内部结构生成效率高无外部依赖排版需要代码硬写学习成本中等版式固定、字段清晰的批量文件HTML转PDFWeasyPrint、wkhtmltopdf、PlaywrightCSS排版能力强页面表现力好依赖浏览器内核或CSS解析器部署体积大页面复杂、样式丰富的报告Word模板填充docxtpl、python-docx模板维护直观业务人员容易上手需要Word环境配合样式还原有偏差文字为主、表格简单的文档在线API各种云PDF服务接入门槛低功能齐备按量计费数据出域二次开发受限低频临时任务我最终选择了ReportLab作为核心生成引擎理由很实际。批量生成证书、对账单这类格式相对固定、数据字段清晰的文档ReportLab的Platypus框架刚好能胜任它提供了一套类似排版引擎的组件模型Paragraph处理文本段落Table处理表格数据而且对中文字体的支持可以通过注册TTF字体解决。相比HTML转PDF的方案它不需要在服务器上额外装浏览器内核相比在线API它能100%离线运行数据完全在自己手里。2.2 最终技术栈与目录结构这个版本的技术栈并不复杂核心依赖就那么几个Python 3.10作为运行环境ReportLab负责PDF生成pandas配合openpyxl处理Excel数据Jinja2做简单的模板字符串渲染PyMuPDF作为生成后校验工具。引入的库都不重部署到一台普通办公电脑或者Linux服务器上都没有问题。整个项目目录我保持了清晰的模块边界pdf_editor_v0.1.3/ ├── main.py # 命令行入口 ├── core/ │ ├── reader.py # 数据读取模块 │ ├── generator.py # PDF生成模块 │ └── validator.py # 结果校验模块 ├── templates/ │ ├── certificate.tpl # 证书模板 │ └── settlement.tpl # 结算报告模板 ├── config/ │ └── settings.yaml # 字体、路径、批次配置 ├── assets/ │ └── fonts/ # 中文字体文件 ├── output/ # 生成结果输出目录 │ └── 20250115/ # 按批次日期分目录 └── logs/ └── run.log # 运行日志这样的目录结构看起来简单但每一层都有明确职责。core目录里三个模块是纯逻辑不关心文件落在哪个目录templates目录放模板文件而不是硬编码在Python代码里这样业务人员要调整文案时不会牵动代码output目录自动按日期分批次避免了多次运行生成文件互相覆盖。早期版本我把模板直接写在代码里每次改样式都要动Python文件后来才拆出来这个改动直接让工具的可维护性上了一个台阶。2.3 为什么不选纯在线工具和低代码平台也有人说你费这个劲做什么用低代码平台拖拽配置一下不就行了吗我的顾虑主要有三点。首先是数据流动路径不透明。低代码平台虽然配置快但数据从Excel导入、经过平台规则转换、最后生成PDF整个过程中间环节是一个黑盒一旦生成结果和预期不一致排查起来非常痛苦。其次是批量性能不可控。有些低代码平台对生成数量有隐性限制一次生成几百份文件时往往要排队甚至超时失败。最关键的是定制灵活性低代码平台顺手的场景是模板完全固定一旦你要根据条件自动隐藏某些字段、动态插入图片、调整表格列宽平台的能力边界很快就会出现。自己用代码控制则完全不同。每一行数据怎么读、每一项字段怎么渲染、每个文件怎么命名全部是显式逻辑。出了问题可以打开日志直接看哪一步失败也可以给某个环节单独写测试。在真实的批量生产环境里这种可控性比配置快重要得多。3. 批量生成核心流程的落地实现实操3.1 第一步数据源读取与预处理批量生成的第一步永远是拿到干净、可靠的数据。我在reader.py模块里封装了一个统一的数据入口它支持从Excel、CSV和SQLite三种数据源读取数据并用统一的数据结构交到生成模块手里。Excel读取用的是pandas加openpyxl引擎网上经常看到的Excel数字变成科学计数法、身份证号变E17这类问题其实是Excel把长数字自动转成了数值类型根源就在于读取时没有指定dtype。我的做法是读取时统一先转成字符串再按字段规则做类型清洗import pandas as pd def read_excel(path, sheet_name0): df pd.read_excel( path, sheet_namesheet_name, dtypestr, # 关键全部按字符串读避免科学计数法和精度丢失 keep_default_naFalse, # 关键空单元格保留为空字符串而不是NaN ) records df.to_dict(orientrecords) for record in records: for key, value in record.items(): if isinstance(value, str): record[key] value.strip() return records这里有两个很容易忽略的细节。第一dtypestr不是万能药如果Excel单元格里本身存的是数值格式pandas读出来依然是数字的字符串形式比如1234.0所以还要对金额、数量这类字段做格式化统一去掉多余的.0。第二keep_default_naFalse必须显式设置否则空单元格会被填充成NaN后续写入PDF时NaN会变成字符串nan这是很多PDF里出现nan问题的来源。3.2 第二步模板设计——从Data到Canvas数据准备好了接下来就是模板渲染。ReportLab的Platypus框架是我用起来最顺手的一套组件体系它把PDF页面当成一块画布提供了几种常用组件SimpleDocTemplate整个PDF文档的容器负责页面大小、页边距、页眉页脚。Paragraph用来渲染文本段落支持部分HTML标签比如粗体、颜色。Table用来渲染表格数据配合TableStyle设置边框、背景色、对齐方式和列宽。Spacer用来控制组件之间的垂直间距。我自己设计模板时没有引入复杂的模板语言而是用了一套极简的占位符规则。模板文件里写的是这种内容结算单编号{{settlement_no}} 结算周期{{period_start}} 至 {{period_end}} 渠道名称{{channel_name}}在generator模块里通过Jinja2的Template类对模板内容做渲染再把渲染好的内容逐行解析成Paragraph和Table。这样做最大的好处是模板文件与业务代码解耦改文案不用动程序同时占位符机制对不熟悉代码的同事也非常友好他们只需要记住字段名和两个花括号的写法。具体的段落渲染逻辑长这样from reportlab.lib.pagesizes import A4 from reportlab.lib.units import mm from reportlab.lib.styles import getSampleStyleSheet, ParagraphStyle from reportlab.platypus import SimpleDocTemplate, Paragraph, Table, TableStyle, Spacer from reportlab.lib import colors def render_content(doc, record): styles getSampleStyleSheet() body_style ParagraphStyle( BodyCN, parentstyles[Normal], fontNameNotoSansCJK, fontSize10.5, leading16, spaceAfter6, ) story [] # 标题 story.append(Paragraph(f结算单 {record[settlement_no]}, body_style)) story.append(Spacer(1, 6 * mm)) # 信息行 info ( f渠道{record[channel_name]} f周期{record[period_start]} 至 {record[period_end]} ) story.append(Paragraph(info, body_style)) story.append(Spacer(1, 4 * mm)) return story一个小建议是做批量生成时尽量把页面上的固定文案和变化数据分开维护。固定文案直接写在模板文件里变化数据只通过占位符注入这样才能保证每一页的版式完全统一不会出现某份文件多一个字、少一个空格这种细节问题。3.3 第三步批量生成与进度控制核心的批量生成循环在generator.py里逻辑说起来很简单遍历数据记录逐条构建PDF文档生成到指定目录。但实际执行时有几个细节决定了这个循环能不能稳定跑完几百条数据。第一个细节是文档构建方式。每生成一份PDF都要重新创建一个SimpleDocTemplate实例并调用build方法。很多人误以为build方法只能调用一次实际上每份PDF对应一次build是完全没有问题的关键是每次都要新建Canvas对象不能在循环外面共用一个PDF对象。import os from datetime import datetime def generate_all(records, template_path, output_dir): os.makedirs(output_dir, exist_okTrue) total len(records) for index, record in enumerate(records, start1): pdf_path os.path.join(output_dir, build_filename(record)) doc SimpleDocTemplate( pdf_path, pagesizeA4, leftMargin15 * mm, rightMargin15 * mm, topMargin15 * mm, bottomMargin15 * mm, ) story render_content(doc, record) doc.build(story) print(f[{index}/{total}] 已生成 {pdf_path})第二个细节是文件名生成规则。如果同一批次的数据记录有重复ID直接按ID命名会互相覆盖文件。我的做法是在生成前先做唯一性校验发现重复ID时报错并终止任务而不是默默覆盖。同时文件名里不要放中文和空格Windows和Linux下都容易出幺蛾子我用的格式是YYYYMMDD_渠道名_结算单号.pdf只保留数字、字母和下划线。第三个细节是性能控制。ReportLab生成一份简单的单页PDF耗时大约在几十到一百毫秒生成一千份也就是一两分钟。但如果在循环里打印大量日志或者每次都把整批数据重新读一遍整体耗时会明显增加。我的做法是日志统一写到log文件终端只输出进度百分比数据读取放在循环外只读一次。3.4 第四步生成结果校验与自动上报批量生成最怕的就是表面成功、实际失败。文件确实生成了但打开一看里面是空的、页面缺了一半、中文字体全部变成方块。手动一份份检查不现实所以我写了validator.py模块用PyMuPDF做自动化校验。校验逻辑分三层。第一层是文件完整性检查确认文件存在且大小不为0第二层是页数检查确认PDF页数符合预期第三层是内容抽样检查用PyMuPDF提取页面文本看关键字段是否出现。对于证书、结算单这类文档我会校验结算单编号和渠道名称两个字段只要这两个字段在提取出来的文本里能匹配到基本可以断定内容渲染成功了。import fitz def validate_pdf(pdf_path, expected_fields): doc fitz.open(pdf_path) if doc.page_count 0: return False, 页面为空 full_text \n.join(page.get_text() for page in doc) for field in expected_fields: if field not in full_text: return False, f缺少字段: {field} doc.close() return True, ok这里有个值得留意的点PyMuPDF提取文本依赖的是PDF里嵌入的文本信息。如果中文是用曲线方式绘制的、或者字体没有被正确嵌入get_text可能提取不到任何内容就会误报失败。所以我在validator里增加了一个开关当确认生成本身没问题但文本提取异常时会改用页面渲染成图片再跟基准图片做对比的方式。当然这个属于进阶校验大部分场景用文本匹配就够了。4. 从v0.1.1到v0.1.3三个版本的踩坑记录4.1 中文乱码与字体嵌入问题第一个版本做出来生成的效果能用但中文全部是乱码和方块。这个问题的根因说穿了很简单PDF的标准字体如Helvetica、Times-Roman只支持Latin-1字符集不包含中文。ReportLab要用中文字体必须先注册一个支持中文的TTF字体文件并告诉它字体名。我在assets/fonts目录里放入了NotoSansCJKsc-Regular.otf也就是思源黑体的简体中文字形然后在程序启动时注册from reportlab.pdfbase import pdfmetrics from reportlab.pdfbase.ttfonts import TTFont pdfmetrics.registerFont(TTFont(NotoSansCJK, assets/fonts/NotoSansCJKsc-Regular.otf))注册之后所有需要用到中文的ParagraphStyle和canvas.setFont都要把fontName指定成NotoSansCJK。这个改动看似简单但有三个容易踩的细节。第一字体文件路径要写成绝对路径或用脚本所在目录拼出来很多新手直接用相对路径就会因为当前工作目录不对导致字体加载失败。第二NotoSansCJK的otf文件本身很大单个字体文件压缩前大约有16MB如果项目要分发到其他机器必须把字体文件一起带上。第三有些字体文件只包含特定字重比如只有Regular没有Bold那么在PDF里加粗中文就不能依赖PDF层面实现而需要在模板文案里直接写加粗的样式或者换用一个同时包含Regular和Bold的字体族。还有一个血泪教训如果生成环境是Linux服务器操作系统的fontconfig配置可能会影响字体的可用性但ReportLab不走fontconfig它直接读TTF文件内容所以只要文件路径正确问题就不大。反而是Windows上有时候会因为杀毒软件占用字体文件导致注册报权限错误这个查了半天才定位到最后把字体文件挪到用户目录下解决了。4.2 批量任务卡死与内存飙升v0.1.2版本遇到了一个更隐蔽的问题任务跑到几百份的时候内存占用一路飙高最后直接卡死。排查下来发现问题出在循环里频繁创建资源却没有释放。ReportLab构建PDF时图片和字体资源会被加载进内存如果循环里处理了图片素材又没有及时关闭文件句柄那么每生成一份PDF内存里就会残留一部分引用几百份下来自然撑不住。解决思路有两个。第一对于确实需要放到PDF里的图片统一走Pillow读取并显式调用img.close()释放资源第二如果单批次数据量特别大比如超过2000份就采用分块生成策略每500份一个批次批次之间强制调用gc.collect()回收不用的对象。这样虽然总耗时略有增加但内存曲线非常平缓长时间跑任务不再担心被系统杀掉。另外一个相关的小坑是临时文件。ReportLab在生成时可能会创建临时文件如果程序异常退出这些临时文件会残留在临时目录。我在main.py里增加了异常捕获和临时目录清理逻辑保证每次运行结束后系统里不会留下垃圾文件。4.3 文件被占用与磁盘写入异常这是所有Windows环境下跑批量生成的人都会遇到的老大难问题目标PDF文件恰好被PDF阅读器打开着或者被杀毒软件扫描锁定导致保存时抛出PermissionError。早期版本遇到这个错误整个任务直接崩溃前面生成的文件全部白干。后来我在生成函数里增加了重试机制碰到权限错误时等3秒再试最多重试三次。更稳妥的方案是先写入临时文件再原子替换。我把每份PDF先生成到output目录下的.tmp子目录文件名加了一个.random后缀生成成功后再用os.replace将它移动到正式的目标文件名。这样即使某个文件写入失败也不会污染已经生成好的文件重跑任务时只需要清理临时目录就可以不需要担心覆盖问题。import tempfile import random import string def safe_generate_pdf(doc, final_path): tmp_dir os.path.join(os.path.dirname(final_path), .tmp) os.makedirs(tmp_dir, exist_okTrue) suffix .join(random.choices(string.ascii_letters, k6)) tmp_path os.path.join(tmp_dir, f{os.path.basename(final_path)}.{suffix}) doc.build(tmp_path) os.replace(tmp_path, final_path)4.4 扫描件与图片型PDF的处理延伸在做PDF工具的过程中我还被问到过很多次扫描件能不能批量处理的问题。扫描件本身是图片打包成的PDF文字是图像的一部分不能直接提取所以这类需求跟批量生成正好反过来本质是批量解析而不是批量生成。v0.1.3版本我并没有在主线里加入完整的OCR能力但在validator的抽样检查环节预留了针对扫描件的处理接口如果提取不到文本就调用本地的OCR引擎做识别再比对关键字段保证文件没生成错。这个方向再往下挖是可以做出一个独立的PDF解析增强工具的比如用PaddleOCR批量提取扫描件里的文字、用PyMuPDF把扫描PDF按页拆成图片、再结合正则表达式做结构化字段提取。不过这是后话了v0.1.3版本先把生成的链路打磨稳这个方向暂时作为扩展点保留。5. 常见问题与排查技巧实录5.1 问题排查速查表把这段时间遇到的高频问题整理成了一张速查表建议直接收藏遇到问题先按图索骥现象可能原因解决方案生成的PDF里中文全部是方块未注册中文字体或字体路径错误检查TTF字体是否注册、setFont是否指定了正确的字体名生成的PDF打不开生成过程中程序异常退出文件没写完整查看日志定位异常确保doc.build执行完成后再做文件替换Excel里的数字变成科学计数法读取时未指定dtype长数字被转成数值读取Excel时dtypestr统一按字符串读取PDF里出现nan字符串空单元格被pandas默认读成NaN设置keep_default_naFalse空值转成空字符串文件名出现乱码或超长文件名中带中文、空格或Excel单元格里的特殊字符使用YYYYMMDD_ID.pdf的命名规则限制字符集批量生成中途内存暴涨图片或字体资源未释放单批数据量过大图片显式close分块生成批次间gc.collect()目标文件被占用导致保存失败PDF文件正被阅读器打开或被安全软件锁定先写临时文件再原子替换增加重试机制不同批次生成的文件混在一个目录输出目录未按批次隔离按日期或批次号自动创建子目录5.2 两个实用的调试技巧第一个技巧是用ReportLab自带的预览能力做快速调试。当你改动了模板样式不想跑完整批数据再查看效果可以在generator里加一个单条调试模式只渲染第一条数据生成到临时目录然后用系统默认PDF阅读器打开。我习惯在main.py里加一个--debug参数设置成Debug模式后只处理一行数据整个调试速度会快很多。第二个技巧是善用PyMuPDF的文本提取来反向验证。哪怕validator模块校验通过了成品PDF打开后用户还是可能发现某个字段错位或者文案重叠。这种视觉层面的问题靠文本提取发现不了我的做法是每隔一定数量抽样一份把PDF页面渲染成PNG图片人工快速扫一眼。自动校验加人工抽检双保险才能保证批量文件的质量。5.3 安全合规敏感信息脱敏与文件权限最后说一个容易被忽略但非常重要的环节安全合规。批量生成的文件很可能包含客户手机号、结算金额、身份证号等敏感信息这些数据一旦从代码里泄漏出去后果很严重。我的做法有三条原则。第一测试数据必须脱敏。开发调试阶段不要用真实客户数据用假名字、假电话号码、假金额确保任何人拿到生成的测试文件都不会泄露真实信息。第二生成目录的访问权限要控制好。如果运行在共享服务器上output目录和logs目录都不要设置成Everyone可读按最小权限原则分配给运行用户即可。第三日志里不要打印完整敏感字段。我在日志里统一对手机号、身份证号做掩码处理比如138****8000既方便排查问题又避免敏感信息全文落盘。另外还要提一句网上经常看到PDF密码恢复、PDF解密这类工具如果需要处理加密的PDF请务必确认你对该文件拥有合法访问权限不要用它来破解他人文件。工具永远是双刃剑使用边界自己要把控好。结尾这个工具从v0.1.1到v0.1.3功能上没加多少但每一版都在解决真实运行环境里的细节问题。我最大的体会是批量生成PDF这种事真正难的不是生成这一步而是整个链路里各种琐碎的异常情况——字体不对、数据不干净、文件被占用、内存撑不住。把这些边界情况一个接一个磨平工具才算真正能用。最后再分享一个小技巧如果你也要在团队里推广类似工具记得把配置项和模板文件单独拎出来让不写代码的同事也能自己维护。这样工具的生命力才会比某个开发自己写的脚本长久得多。后面我计划给这个版本加上定时触发和邮件分发的能力让批量报告真正实现全自动化。