接到这个需求的时候我还挺乐观的报表生成PDF嘛Python里框架一堆找个库画上去不就行了。结果第一版交付出去对方打开文件满屏都是方框和问号中文字体全乱套。后来我才发现ReportLab这套老牌PDF生成库虽然文档齐全但“中文支持”这层窗户纸几乎每个新手都要捅破一次。这篇文章不是复述官方文档而是把我在项目里折腾字体处理与中文排版的实战记录拿出来提炼成5个关键技巧。主要解决三类问题一是字体注册和加载二是段落、表格里的中文排版三是批量生成PDF时的性能和坑点。适合用Python做PDF报表、合同、发票、电子书导出或者想把Web页面转成正式文档交付的开发同学参考。你看完可以直接照着抄至少能少走好几天的弯路。1. 为什么中文在ReportLab里总是乱码1.1 一次真实项目的乱码现场当时我在做内部订单系统需要把每月的销售明细生成一份PDF发邮件给业务部门。数据都是从数据库里查出来的Python处理字符串完全没毛病代码里看到的中文也都是正常的。但生成出来的PDF文件英文数字一切正常所有中文全部变成小方框或者直接消失。最诡异的是程序不报错日志里也没有任何异常。我一度怀疑是PDF阅读器的问题换了三个阅读器结果一模一样。最后查了一圈资料才明白ReportLab默认使用的14种标准字体全是Type1字体。这类字体在设计时只覆盖了拉丁字符集PDF阅读器在没有嵌入中文字形的情况下根本不知道该怎么渲染“订单”这两个字于是只能东拼西凑凑出个占位符。1.2 默认字体与中文编码之间的差距要理解这个问题得先搞清楚PDF里的字体机制。PDF文档不像HTML那样依赖系统字体它更接近一份“印刷文件”用到了什么字体就会把对应字形数据嵌进去。ReportLab默认的Helvetica、Times-Roman、Courier都是几十年前定下的PDF标准字体覆盖范围只有西文、数字和基础标点。它们不是通过设置编码能解决的因为字体本身就没有中文的glyph。很多新手在这里会走偏以为乱码是字符串编码问题于是给字符串加u前缀、转成UTF-8、用encode解码折腾半天完全没用。核心结论一句话乱码不是编码问题是字体缺失问题。你需要做的是把一套中文字体真正注册进ReportLab让它在生成PDF时把中文字形嵌入进去。我的建议是把“编码”两个字从脑子里删掉换成“字形”和“字体文件”思路一下子就顺了。2. 技巧一用TTFont注册中文字体而不是直接改fontName2.1 TTFont的注册与使用ReportLab支持通过reportlab.pdfbase.ttfonts.TTFont加载TrueType和OpenType字体。注册方法很简单from reportlab.pdfbase import pdfmetrics from reportlab.pdfbase.ttfonts import TTFont # 注册一个黑体字体名字可以自己起但要全局唯一 pdfmetrics.registerFont(TTFont(MyHei, simhei.ttf))注册完成后在所有需要设置字体的地方使用你起的这个名字比如ParagraphStyle里的fontNameMyHeifrom reportlab.lib.styles import ParagraphStyle body_style ParagraphStyle( nameBodyStyle, fontNameMyHei, fontSize12, leading20, )如果字体文件和脚本不在同一目录TTFont的第二个参数要传完整路径。在Windows上调试时我习惯直接用系统字体目录里的字体比如C:\Windows\Fonts\simhei.ttf。但有一点要提醒生产环境如果是Linux服务器系统字体目录里通常没有微软家族的字体这时候最稳妥的办法是把字体文件放到项目目录用相对路径读取或者通过环境变量配置路径。还有一个细节registerFont是全局注册同一个进程只需要注册一次。如果在一个函数里反复注册同名不同文件的字体ReportLab不会立刻报错但PDF里可能同时嵌入两套字体数据体积白白变大甚至出现渲染错乱。2.2 字体选择与版权注意开源项目或商业系统里我不建议直接拷贝宋体、黑体这类微软字体文件到服务器上版权风险控制一下。比较好用的是思源黑体或Noto Sans CJK SCAdobe和Google开源可免费商用。思源黑体在Linux上安装包名字通常是fonts-noto-cjk各发行版软件源都有。如果你只是本地跑脚本用系统自带的sarasa更纱黑体体验也很好中文、英文字形都比较均衡。衬线体推思源宋体Source Han Serif适合合同、公告这类需要正式感的文档。字体选择直接影响PDF风格标题用黑体加粗正文用宋体表格数字用无衬线的思源黑体都对。有些字体文件体积巨大思源黑体完整版动辄几十MB生成出的PDF也会变大。ReportLab会对嵌入字体做子集化只嵌用到的字符所以实际PDF不会像字体文件那么大但首次解析字体文件还是需要一点时间的。2.3 注册后为什么有些地方仍不生效这是新手高频问题明明注册了MyHei在canvas.drawString里也写了canvas.setFont(MyHei, 12)可中文还是方框。排查思路很简单drawString只负责画字它不会自动处理换行更不会做字符集转换。如果你注册的字体文件路径不对或者字体名没匹配上它会静默回退到默认字体。建议代码里捕获异常from reportlab.pdfbase.ttfonts import TTFError try: pdfmetrics.registerFont(TTFont(MyHei, font/simhei.ttf)) except TTFError as e: print(f字体注册失败: {e})另外canvas.setFont和ParagraphStyle里的fontName作用域不同。你在Style里设置了中文但表格里直接用TableStyle的FONTNAME覆盖了表格里的中文照样用默认英文字体渲染。这类问题不是“注册不生效”而是你遗漏了具体组件的字体设置。3. 技巧二TTC文件要学会拆分和定位3.1 什么是TTCReportLab为什么绕不开很多中文字体安装后是.ttc后缀也就是TrueType Collection一个文件里打包了多个字体。比如Windows的simsun.ttc包含宋体和新宋体msyh.ttc包含微软雅黑和雅黑Light。ReportLab的TTFont对TTC支持不完整它试图读取第一个字体时可能成功但如果你需要里面的第二个字体或者字体文件名是中文导致路径解析出问题就会遇到各种奇怪报错。最典型的错误是ValueError: attempt to read TTC font with more than one font in the file或者生成PDF后某些字符渲染成了空白。我踩过一次泥土比较深的坑在Linux上用Python包直接加载Windows拷贝过来的msyh.ttc本地测试没问题部署到服务器上却一直报字体头损坏。后来确认是版本差异Windows 10的TTC头部数据比ReportLab预期的新跨平台兼容性很差。3.2 用fontTools提取子字体既然TTC不稳定最简单的办法就是拆分成独立的TTF文件。这块用fontTools非常方便from fontTools.ttLib import TTCollection ttc TTCollection(msyh.ttc) for idx, font in enumerate(ttc.fonts): font.save(fmsyh_{idx}.ttf) print(f导出第 {idx} 个字体: {font.name.getDebugName(4)})如果你不想写代码同样可以用命令行工具python -m fontTools.ttLib -o msyh_0.ttf msyh.ttc不过fontTools.ttLib的命令行对TTC拆分的参数细节不同版本有差异还是建议直接写循环。拆分后你可以打开每个TTF文件确认字体名称然后把需要的文件放到项目字体目录用TTFont(MyYaLi, font/msyh_0.ttf)加载。还有一类情况Linux服务器上可以用包管理器装中文字体比如Debian/Ubuntu执行sudo apt install fonts-noto-cjk安装后字体文件通常在/usr/share/fonts/opentype/noto/下是.ttc或.otf比如NotoSansCJK-Regular.ttc。如果你不想拆它也可以直接用reportlab.pdfbase.ttfonts.TTFont尝试加载某些版本的ReportLab能正确处理单字体TTC。但为了保险我一般还是会用fontTools拆一版放在专属目录避免服务器字体包升级导致路径变化。4. 技巧三段落排版用Paragraph而不是手动拼接文本4.1 Paragraph是中文排版的正确姿势刚接触ReportLab的人很容易陷入一个误区用canvas.drawString画所有文本然后自己手工算坐标、算换行位置。单个字符串没问题但遇到长文本就崩了因为drawString根本不会自动换行中文和英文混排时更是雪上加霜。正确的做法是使用Paragraph对象。它负责处理自动换行、对齐、段落间距、缩进还可以通过XML风格的标签实现局部样式比如高亮、加粗、上标。ParagraphStyle是核心配置对象from reportlab.lib.pagesizes import A4 from reportlab.lib.styles import ParagraphStyle from reportlab.platypus import Paragraph body_style ParagraphStyle( body, fontNameMyHei, fontSize12, leading20, # 行距中文建议1.5倍左右 firstLineIndent24, # 首行缩进两个12号字 alignment0, # 0左对齐 1居中 2右对齐 4两端对齐 spaceAfter10, ) p Paragraph(这里是正文内容可以自动换行不会变成一坨挤到页面外面, body_style)ParagraphStyle里的leading是行距很重要。中文排版的阅读习惯对行距很敏感行距太小字会挤在一起行距太大版面又显得散。我的经验是12号字配18到20的leading比较舒服16号字配24到26。这个数据不是乱拍的是从Word默认行距1.5倍换算来的经验值。4.2 中英文混排和标点换行问题Paragraph默认的断行规则是按字符断行对英文句子它会尽量按单词断避免破坏单词完整性。但中文里没有空格默认规则遇到行尾标点可能处理得很丑比如逗号跑到行首。这时候可以在ParagraphStyle里设置wordWrapCJKbody_style ParagraphStyle( body_cjk, fontNameMyHei, fontSize12, leading20, wordWrapCJK, )设置之后文本会按照CJK规则断行中文标点不会出现在行首英文单词在超长时会按字符截断。但要注意副作用如果文本里有很长的英文URL或连续数字比如https://example.com/very/long/path开启CJK后可能会被硬生生截断影响点击。我的处理办法是把这些特殊内容放到独立的Paragraph里不套用wordWrapCJK或者用link标签包起来。另外Paragraph内部支持XML标签所以文本里的、、会被解析为标签导致内容丢失或报错。从用户输入取数据时要先转义from xml.sax.saxutils import escape safe_text escape(user_content) p Paragraph(safe_text, body_style)这个坑非常隐蔽用户填了一个“价格100元”生成PDF时直接给了个样式解析错误排查了半天才发现是尖括号搞的鬼。4.3 首行缩进与分页控制中文排版基本都有首行缩进两字符的习惯。ParagraphStyle里的firstLineIndent是按point计算的两个12号字就是24pt。但这里有个容易忽视的地方如果你在传入Paragraph的文本里自己加了全角空格来缩进效果会很乱因为不同字体里全角空格宽度不一致。正确做法是统一交给firstLineIndent。长文档场景下Paragraph还有一个很有用的属性叫keepWithNext意思是这个段落能不能和下一个段落分开在不同的页面。比如标题后面紧跟正文如果标题停在页尾、正文跑到下一页非常影响阅读。设置标题样式的keepWithNextTrueReportLab会自动把标题往下挪到跟正文一起heading_style ParagraphStyle( heading, fontNameMyHei, fontSize16, leading24, spaceBefore12, spaceAfter6, keepWithNextTrue, )5. 技巧四表格单元格里的中文排版要单独处理5.1 表格流水线机制与多行问题用Platypus做表格最头疼的坑是Table里的cell如果直接塞字符串它默认不会自动换行内容超出列宽只会被截断或者把列撑破。原因在于底层绘制逻辑是单行文本画布不会调用Paragraph的换行算法。所以只要单元格内容可能是中文长文本就一定要把内容包装成Paragraph对象from reportlab.platypus import Table, TableStyle data [ [Paragraph(b订单号/b, head_style), Paragraph(b客户名称/b, head_style)], [Paragraph(SO202405001, cell_style), Paragraph(北京一家做软件的公司, cell_style)], ] table Table(data, colWidths[100, 200]) table.setStyle(TableStyle([ (GRID, (0, 0), (-1, -1), 0.5, #999999), (VALIGN, (0, 0), (-1, -1), MIDDLE), ]))这里有两个容易踩的细节一是表格行高不会自动计算Paragraph的高度如果你没显式设置rowHeightsReportLab会根据样式里的leading粗略估算。内容行数多时行高可能不够文字会被压到单元格外面。解决办法是手动指定rowHeights[30, 60]或者用Table(..., repeatRows1)让表头跨页重复。5.2 表格样式与中文对齐表格里中文对齐也很讲究。中文不像英文那样靠空格对齐列宽不同时居中和左对齐表现差距很大。一般正文单元格我喜欢左对齐表头居中。TableStyle里设置table.setStyle(TableStyle([ (ALIGN, (0, 0), (-1, -1), LEFT), (ALIGN, (0, 0), (-1, 0), CENTER), (FONTNAME, (0, 0), (-1, -1), MyHei), (FONTSIZE, (0, 0), (-1, -1), 10), ]))FONTNAME的范围是单元格索引如果单元格里是ParagraphTableStyle的FONTNAME未必能覆盖Paragraph内部自己的字体设置。所以最稳妥的办法是在ParagraphStyle里把字体名和字号都设好TableStyle只管边框、背景色、对齐这些视觉属性。否则会出现一种怪现象表格看起来用了中文字体但某个单元格里又冒出默认英文字体。5.3 表格列宽与自动缩放Excel表格习惯按内容自适应列宽但ReportLab的Table不会帮你做这件事。colWidths必须手动指定而且所有列宽之和要小于页面可用宽度。A4纸默认横向尺寸是595pt左右页边距各36pt内容宽度大约523pt。如果你有三列可以设置成[100, 200, 200]加起来500剩下23pt留空。如果需要让表格自动填满整页宽度可以用Table(data, colWidthsNone, hAlignCENTER)然后让ReportLab根据内容自动分配但这样列宽比例可能不符合预期。我的做法是先算好总宽度再按百分比分配usable_width A4[0] - 2 * 36 table Table(data, colWidths[usable_width * 0.2, usable_width * 0.5, usable_width * 0.3])6. 技巧五字体加载与缓存优化6.1 全局缓存字体对象做单个PDF时性能问题不明显。但当你循环生成几百个PDF每个PDF里还反复registerFont程序可能卡到怀疑人生。registerFont要做的事包括读文件、解析字体表、构建字形映射表这套流程对大型CJK字体来说开销不小。我自己把字体注册封装成全局函数保证一个进程里只注册一次from reportlab.pdfbase import pdfmetrics from reportlab.pdfbase.ttfonts import TTFont _FONT_REGISTERED set() def ensure_font_registered(font_name, font_path): if font_name in _FONT_REGISTERED: return pdfmetrics.registerFont(TTFont(font_name, font_path)) _FONT_REGISTERED.add(font_name)这样每份文档生成时调用ensure_font_registered(MyHei, font/simhei.ttf)第一次会加载后续直接跳过。对于批量按天生成报表的场景性能提升非常明显。6.2 派生字体族中文加粗不能只靠样式还有一个常见坑中文没有原生Calibri那样的“加粗版”但很多PDF要求标题宋体加粗。如果只注册一个Regular字体ParagraphStyle里设置fontNameMyHei加fontWeightbold不会生效Paragraph的加粗是靠解析b标签最终还是会映射到一个字体上。解决办法是用registerFontFamily把常规、粗体、斜体、粗斜体都绑定起来pdfmetrics.registerFont(TTFont(MyHei, simhei.ttf)) pdfmetrics.registerFont(TTFont(MyHei-Bold, simhei_bold.ttf)) pdfmetrics.registerFontFamily( MyHei, normalMyHei, boldMyHei-Bold, italicMyHei, boldItalicMyHei-Bold, )注册之后ParagraphStyle的fontNameMyHei以及文本里的b加粗/b就能正确渲染成粗体字形。如果找不到粗体字体文件可以退而求其次用canvas.setFont(MyHei, 12)再把文字画两遍模拟加粗但这只是权宜之计效果一般。6.3 用BytesIO避免频繁写磁盘批量生成PDF时很多人喜欢先写临时文件再批量清理其实完全可以用内存字节流from io import BytesIO from reportlab.pdfgen import canvas buf BytesIO() c canvas.Canvas(buf) c.drawString(100, 700, 示例内容) c.showPage() c.save() buf.seek(0) pdf_bytes buf.getvalue()这样既能防止磁盘碎片也省去清理临时文件的步骤。需要注意的是生成特别大的PDF比如几百页全放内存可能占几百MB权衡后还是写临时文件更稳。内存和磁盘的取舍没有绝对标准我个人的习惯是单文件小于20MB走内存大于20MB落盘避免内存暴涨。6.4 字体文件与临时资源释放用TTFont加载字体后字体对象会常驻在ReportLab内部缓存里这是正常的。但如果你在循环里用BytesIO加载字体文件而不保留底层数据的引用可能出现文件句柄释放不及时的情况。尽量把字体文件保存为实体文件后直接传路径给TTFont避免从内存二进制流注册字体时对字节数组生命周期管理不当造成的怪异问题。7. 一个可以直接抄的完整示例7.1 示例需求假设要生成一份带标题、正文段落、表格的PDF包含中英文混排内容并在页脚显示页码。这里把所有技巧串起来你会看到完整的字体注册、样式配置、表格封装和分页流程。7.2 完整代码# -*- coding: utf-8 -*- from io import BytesIO from reportlab.lib.pagesizes import A4 from reportlab.lib.styles import ParagraphStyle from reportlab.lib.units import cm from reportlab.pdfbase import pdfmetrics from reportlab.pdfbase.ttfonts import TTFont from reportlab.platypus import ( BaseDocTemplate, Frame, PageTemplate, Paragraph, Spacer, Table, TableStyle ) FONT_PATH font/NotoSansCJKsc-Regular.otf FONT_BOLD_PATH font/NotoSansCJKsc-Bold.otf pdfmetrics.registerFont(TTFont(NotoSC, FONT_PATH)) pdfmetrics.registerFont(TTFont(NotoSC-Bold, FONT_BOLD_PATH)) pdfmetrics.registerFontFamily( NotoSC, normalNotoSC, boldNotoSC-Bold, italicNotoSC, boldItalicNotoSC-Bold, ) title_style ParagraphStyle( title, fontNameNotoSC-Bold, fontSize18, leading26, alignment1, spaceAfter12, ) head_style ParagraphStyle( head, fontNameNotoSC-Bold, fontSize11, leading16, alignment1, textColorwhite, ) cell_style ParagraphStyle( cell, fontNameNotoSC, fontSize10, leading15, wordWrapCJK, ) # 页面模板带页脚页码 def add_page_footer(canvas, doc): canvas.saveState() canvas.setFont(NotoSC, 9) canvas.drawCentredString(A4[0] / 2, 1 * cm, str(canvas.getPageNumber())) canvas.restoreState() doc BaseDocTemplate( demo.pdf, pagesizeA4, leftMargin2 * cm, rightMargin2 * cm, topMargin2 * cm, bottomMargin2 * cm, ) frame Frame(doc.leftMargin, doc.bottomMargin, doc.width, doc.height, idmain) doc.addPageTemplates([PageTemplate(idpage, frames[frame], onPageadd_page_footer)]) story [] story.append(Paragraph(订单月度汇总报告, title_style)) story.append(Spacer(1, 12)) body_text (本报告统计了本月的订单数据包括订单数量、客户分布和收入概况。 需要说明的是所有数据均来自内部系统导出已经过验证。 中文内容在生成PDF时会按CJK规则自动换行 不会再将文字挤到页面之外。) story.append(Paragraph(body_text, cell_style)) story.append(Spacer(1, 12)) table_data [ [Paragraph(订单号, head_style), Paragraph(客户名称, head_style), Paragraph(金额, head_style)], [Paragraph(SO202405001, cell_style), Paragraph(北京某信息技术公司, cell_style), Paragraph(1,280.00, cell_style)], [Paragraph(SO202405002, cell_style), Paragraph(上海某贸易有限公司, cell_style), Paragraph(3,590.00, cell_style)], ] orders_table Table(table_data, colWidths[5 * cm, 7 * cm, 4 * cm], repeatRows1) orders_table.setStyle(TableStyle([ (BACKGROUND, (0, 0), (-1, 0), #4F81BD), (GRID, (0, 0), (-1, -1), 0.5, #999999), (VALIGN, (0, 0), (-1, -1), MIDDLE), (ALIGN, (0, 0), (-1, -1), LEFT), (ALIGN, (2, 0), (2, -1), RIGHT), (ROWBACKGROUNDS, (0, 1), (-1, -1), [None, #F3F3F3]), (TOPPADDING, (0, 0), (-1, -1), 6), (BOTTOMPADDING, (0, 0), (-1, -1), 6), ])) story.append(orders_table) doc.build(story)这个示例里标题用了粗体字体族正文开启了wordWrapCJK表格用Paragraph包裹所有中文单元格页脚页码用PageTemplate的onPage回调实现。把字体文件路径换成你本地的路径代码应该能直接跑通。7.3 常见问题速查表现象原因解决办法中文全是小方块使用的字体没有中文字形注册中文字体并指定fontName报错Unknown font字体名在registerFont前被使用调整注册顺序或检查字体名拼写文字不自动换行用了drawString而非Paragraph改用ParagraphParagraphStyle表格内容被截断单元格塞字符串不走换行引擎单元格内容包Paragraph打开PDF后中文是乱码字体路径错误或注册失败被忽略捕获TTFError打印异常字体加粗不生效没有注册粗体字体族用registerFontFamily绑定粗体TTC文件加载报错ReportLab不兼容多字体TTC用fontTools拆分TTF超大PDF生成慢重复注册字体、频繁写磁盘全局缓存字体用BytesIO用户输入含尖括号报错Paragraph把文本当XML解析用xml.sax.saxutils.escape转义7.4 一个小技巧先在小样本上验证再跑全量最后一个十分受用的建议是先用三五行数据生成一页测试PDF确认字体、标题、表格、页码都没问题再跑全量数据。全量数据量大时排查PDF布局问题非常折磨人你可能分不清是数据内容导致的格式异常还是代码逻辑本身有坑。先小后大能帮你把变量控制到最少快速定位是字体问题、列宽问题还是数据问题。我个人在实际操作中的体会是ReportLab处理中文本身并不复杂难的是你一开始不知道有这么多细节需要同时配合。字体注册只是第一步Paragraph、Table、CellStyle这些组件各自有自己的字体作用域谁漏了谁就乱。你要是能把这几个组件的字体和样式都统一梳理清楚中文PDF这块基本就稳了。以后再遇到类似需求直接翻这篇文章的示例代码改改数据和样式就能交付。
