最早在 ReportLab 里输出中文我以为就是写一行drawString的事直到第一次在生成的 PDF 里看到一片豆腐块——中文全变成了方框。后来排查才发现ReportLab 内置的 14 个 PDF 标准字体里根本没有中文字形你要是没主动注册字体它连把字符串映射到正确字形轮廓的入口都找不到。这篇文章要讲的就是围绕“字体处理与中文排版”总结出的 5 个关键技巧字体注册 API 怎么选、段落对象怎么用、中英混排怎么切字体、中文排版参数怎么调、字体嵌入怎么查。适合两类人一类是刚接触 Python ReportLab想快速把带中文的报告、单据生成成 PDF另一类是已经能跑通基本功能但总在换行和字体美观上反复踩坑的人。读完之后你能得到一套能落地的中文 PDF 生产方案也能理解每个配置背后的逻辑而不是拿来一段能跑但说不清道不明的代码。1. 乱码与报错的真正源头ReportLab 的标准字体只覆盖拉丁字符集1.1 PDF 标准 14 种字体里没有任何中文字形很多人第一次接触 ReportLab会用canvas.drawString(100, 100, 中文内容)画文字。画完一看 PDF全是方框或者干脆抛异常。问题不在于 ReportLab 不支持中文而在于它默认带的字体是 Helvetica、Times、Courier 这一系列 PDF 标准字体。这套字体由 PDF 规范固定覆盖范围以拉丁字符为主中文、日文、韩文这类 CJK 字形根本不在里面。这里要多说一句PDF 里的字体不是“渲染的时候去系统里现找”而是要么用标准的 14 种字体要么把实际用到的字形文件嵌入到 PDF 内部。ReportLab 默认走的是前者所以中文字符没有对应字形只能显示为占位方框。这和网页前端缺字体时的“tofu”方块体验差不多。如果你打开生成的 PDF发现中文位置是空白的、方框的或者在某些阅读器里看起来像乱码第一反应就应该是字体没注册或者注册了但没真正用上。这个判断基本能覆盖 80% 的“中文 PDF 乱码”问题。1.2 两种常见的失败模式其实是同一个病根我在项目里见过两种表现完全不同的报错最后定位到同一个原因。第一种控制台直接报错UnicodeEncodeError: latin-1 codec cant encode characters in position 0-1: ordinal not in range(256)这种多半是 ReportLab 内部想把中文字符窄化成某种编码时发现办不到。第二种最迷惑人程序没报错PDF 也生成成功了但所有中文全是“□□□”。这时候千万别去怀疑文本编码先查字体。排查顺序我建议这样做确认目标字体文件存在并且有读取权限。确认 PDF 构建时使用段落或画布的fontName和注册字体名完全一致。用 PDF 阅读器打开文件查看字体列表里实际嵌入了哪些字体。如果还是方块换一个字体文件单独测试排除字体本身损坏或特殊格式问题。这个链路我后来在好几个项目里复用基本 5 分钟能定位。1.3 那些“零注册”的旧偏方为什么不可靠网上能搜到一些老办法说不注册字体也能输出中文比如自己手动把字符替换成实体的 PDF 指令。这类方案在某些极简场景能跑但完全绕过了字体映射遇到换行、对齐、复制粘贴文本时就露馅。技术上不是不能做但它违背了“让 PDF 正确承载文本”的初衷生产环境里我不推荐。正确做法就是老老实实走字体注册让 ReportLab 知道你的中文字体文件在哪、叫什么、包含哪些字形。这也是后面 5 个技巧的共同前提。2. 技巧一中文字体注册要认清 APITTF 和 TTC 完全是两码事2.1 标准注册姿势pdfmetrics TTFontReportLab 注册中文字体的核心代码长这样from reportlab.pdfbase import pdfmetrics from reportlab.pdfbase.ttfonts import TTFont font_path C:/Windows/Fonts/simhei.ttf pdfmetrics.registerFont(TTFont(SimHei, font_path))之后你在ParagraphStyle里把fontName写成SimHei或者在canvas.setFont(SimHei, 12)里使用就行。这里第一个参数是字体在 ReportLab 内部的“别名”你可以随便起但建议起容易识别的名字方便后期排查。有一个容易忽略的细节Windows 路径里的反斜杠在普通字符串里会被当成转义符比如C:\Windows\Fonts\simhei.ttf里的\W和\F在某些 Python 版本或平台下会出问题。我习惯统一用正斜杠C:/Windows/Fonts/simhei.ttf省心。2.2 系统里的 .ttc 集合字体要额外指定 subfontIndex很多人照着教程写TTFont(MSYH, C:/Windows/Fonts/msyh.ttc)结果报错或者生成后发现字形不对甚至 Ignore 掉整个字体。原因很简单msyh.ttc、simsun.ttc不是单个字体文件而是多个字体打包在一个容器里的集合字体TrueType Collection。一个 .ttc 里通常有多个字体比如微软雅黑常规体和微软雅黑 UI 等。ReportLab 加载这种文件需要明确告诉它取第几个子字体用subfontIndex参数from reportlab.pdfbase import pdfmetrics from reportlab.pdfbase.ttfonts import TTFont pdfmetrics.registerFont( TTFont(MSYH, C:/Windows/Fonts/msyh.ttc, subfontIndex0) )subfontIndex从 0 开始算。simsun.ttc的第一个子字体通常就是宋体msyh.ttc的第一个子字体就是微软雅黑常规体。如果你需要粗体或不同字重可能需要子字体序号 1、2。我遇到过一次因为没写subfontIndex字体注册成功但 PDF 内容全是空白的诡异问题比直接报错更难排查。从那以后凡是 .ttc 文件我一律显式指定subfontIndex绝不靠默认值。2.3 服务器上没装中文字体怎么办本地开发用 Windows 字体没问题但一到部署环境就翻车。很多 Linux 服务器默认不带微软雅黑、宋体如果代码写死了C:/Windows/Fonts/...部署上去直接找不到文件。生产环境常用的替代方案是用思源黑体或者文泉驿微米黑。思源 Sans CJK 系列的 .otf/.ttc 版本在 Linux 下兼容性不错注册方式和前面一样pdfmetrics.registerFont( TTFont(NotoSans, /usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc, subfontIndex0) )部署前可以写个启动检查确认字体文件存在再继续构建任务避免生成一批废 PDF 才报警。另外思源黑体部分 .otf 是 CFF 轮廓的 OpenTypeReportLab 的TTFont处理 TrueType 轮廓的字体更稳妥所以我优先选 .ttc 或者明确标注“TrueType”的版本。3. 技巧二drawString 只适合画单行文本中文段落换行要用 Paragraph3.1 canvas.drawString 的三个隐藏限制把中文字体注册好了之后drawString确实能画出中文。但如果你要输出长段落它有三个绕不过去的限制。第一个限制是它不自动换行。canvas.drawString(x, y, text)只是在坐标点把整段文本横着画出去超宽就超出页面不会自动折行。第二个限制是它不处理分页。你画到页面底部它不会把剩余文字推到下一页得自己计算坐标。第三个限制是它没有段落级样式。行距、首行缩进、两端对齐全都得手动算。所以我的原则是drawString只用来画页眉、页脚、签名这样的单行固定文本。凡是正文内容都交给 ReportLab 的 Platypus 流程对象也就是Paragraph。3.2 用 Paragraph 接管多行中文文本来看一个最小可运行的示例from reportlab.lib.enums import TA_JUSTIFY from reportlab.lib.pagesizes import A4 from reportlab.lib.styles import ParagraphStyle from reportlab.pdfbase import pdfmetrics from reportlab.pdfbase.ttfonts import TTFont from reportlab.platypus import SimpleDocTemplate, Paragraph pdfmetrics.registerFont( TTFont(MSYH, C:/Windows/Fonts/msyh.ttc, subfontIndex0) ) body_style ParagraphStyle( namecn-body, fontNameMSYH, fontSize12, leading20, alignmentTA_JUSTIFY, firstLineIndent24, ) doc SimpleDocTemplate(chinese_demo.pdf, pagesizeA4) content ( 这是一段用于验证 ReportLab 中文排版的中文文本。 只有正确注册中文字体Paragraph 才能找到对应的字形。 Paragraph 会自动处理换行和分页中文正文用它最合适。 ) doc.build([Paragraph(content, body_style)])这里Paragraph接收的是带轻量标记的文本默认情况下它会自己拆行。中文文本没有空格按英文的“找空格断行”逻辑按理说会出问题但 ReportLab 对 CJK 字符做了一套按字符拆行的处理所以你不需要手工塞空格。实际用下来中长段落的换行效果基本可用。3.3 wordWrap 参数中文长文本的另一个开关如果你的文本里混了很多长数字串、英文缩写或者内容是从数据库里拼出来的可能出现某些词把行撑破的情况。这时候可以给ParagraphStyle加一个参数ParagraphStyle( cn-body, fontNameMSYH, fontSize12, leading20, wordWrapCJK, )wordWrapCJK会让断行逻辑更贴合中日韩文本的习惯遇到超长内容也能按字符切开而不是死等空格。它不是万能药但在我处理客服备注、用户地址这类不可控文本时确实减少了很多溢出问题。4. 技巧三中英文混排别迷信一个字体font 标签做局部切换4.1 中英文混排时一个字体带来的观感问题业务系统里很少有纯中文文本最常见的是“订单号 ABC123 已发货预计 3 天内送达”这种中英混排。如果整段都用中文字体渲染英文和数字会使用中文字体里的拉丁字形。问题在于一些中文字体里的拉丁字形是全宽或者半宽和正文的英文字体放在一起视觉间距非常怪。比如“ABC123”在宋体里被拉得又宽又松明明是一串代码看起来像被空格隔开了一样。解决思路不是换字体而是让英文、数字各自回到更合适的字体上去。ReportLab 的Paragraph内嵌了一个简单的标记解析器支持在文本中间临时切换字体。4.2 用font标签做局部字体切换text ( 订单号 font nameHelveticaABC123/font 已发货 预计 font nameHelvetica3/font 天内送达。 )font标签里的name可以是 ReportLab 内置标准字体名也可以是前面注册过的自定义字体名。渲染时这段文本里的 “ABC123” 会用 Helvetica 绘制其他部分继续用ParagraphStyle里指定的fontName。还有个更常见的用法是给英文代码配一个代码感强的字体from reportlab.pdfbase import pdfmetrics from reportlab.pdfbase.ttfonts import TTFont pdfmetrics.registerFont(TTFont(RobotoMono, fonts/RobotoMono-Regular.ttf))然后在文本里编号 font nameRobotoMonoREF-2024-009/font。这个方式比把英文和中文拆成多个段落在同一行里拼坐标靠谱得多既不影响换行也不影响对齐。4.3 文本本身带的尖括号必须转义既然是标记解析器就引出了一个新的坑如果正文里真的包含或字符比如很多前端代码、比较表达式、邮件模板里的标签不处理会被 ReportLab 当成富文本标签吞掉。处理方式和 HTML 转义一致替换成lt;替换成gt;替换成amp;我写过一个小函数在拼段落之前统一处理from xml.sax.saxutils import escape safe_text escape(raw_text) safe_text safe_text.replace(\n, br/)br/是 Paragraph 里的换行标签把原始文本里的换行符转成它可以保留原文的段落结构。这段代码后来帮我省了不少事尤其是数据来自备注框这种自由文本时。4.4 字体名做映射别把路径写死在代码里中英混排牵扯到字体选型更要考虑部署环境差异。我会在项目里放一个字体配置模块把“逻辑字体名”和“具体字体路径”分开FONT_MAP { default: { cn: TTFont(NotoSans, /usr/share/fonts/noto/NotoSansCJKsc-Regular.otf, subfontIndex0), en: TTFont(Arial, /usr/share/fonts/ari/arial.ttf), }, windows: { cn: TTFont(MSYH, C:/Windows/Fonts/msyh.ttc, subfontIndex0), en: TTFont(Arial, C:/Windows/Fonts/arial.ttf), } }启动时根据平台选一套注册。这样本地调试和生产环境不用改业务代码只需要维护字体清单。这个方法在容器化部署时尤其有用。5. 技巧四首行缩进、行距、段间距中文排版的三个隐藏参数5.1 firstLineIndent 别写死按字号动态算中文排版最明显的特征是首行缩进两字符。ReportLab 的ParagraphStyle里有firstLineIndent但这里有个细节想要“两字符”应该用字号乘 2 来算而不是写死一个像素值。比如字号 12pt两字符缩进就是 24ptfont_size 12 ParagraphStyle( cn-body, fontSizefont_size, firstLineIndentfont_size * 2, # 保持两字符缩进 )如果你直接写firstLineIndent24之后把字号改成 14pt缩进还是 24pt看起来就只有不到两字符了。用公式动态算整体排版比例才不会散。5.2 leading 行距要按中文字号手动放大leading是段落行距ReportLab 里如果不设置它会沿用字体默认值。对中文来说默认行距经常偏紧中文方块的视觉密度大行与行之间如果不留够空间整段文字会挤成一团。我常用的经验值是字号的 1.6 到 1.8 倍ParagraphStyle( cn-body, fontSize12, leading20, # 12 * 1.67 ≈ 20 )如果有人觉得 1.6 倍还紧可以放大到 2 倍。行距没有绝对标准取决于你的字号和阅读场景但至少不要用默认值硬撑这是中文排版观感提升最明显的一步。5.3 对齐方式、段前段后间距一起管理正文一般用两端对齐TA_JUSTIFY这个不用多说。但段落之间如果紧挨着长文档读起来很难受我通常会在样式里补上spaceAfterParagraphStyle( cn-body, fontSize12, leading20, firstLineIndent24, spaceAfter8, )在 Platypus 的SimpleDocTemplate.build()里也可以直接用Spacer控制间距。两段之间我一般用Spacer(1, 6)或者Spacer(1, 12)根据页面宽度试一次就定了。5.4 中文标点的行首禁则ReportLab 没有现成开关中文排版里有一类特殊情况叫“标点禁则”意思是句号、逗号、右括号这类标点不应该出现在行首。ReportLab 本身没有做这个规则的开箱配置长文本跑下来确实可能出现某一行第一个字是句号或者右括号的情况。我处理的办法是在文本拼接阶段做预处理把标点前移避免它落在行首。更粗暴的办法是手动控制段落长度让行尾刚好落在合适位置。这两种方案都有点“土”但对大多数内部文档够用了。如果你的项目对排版要求严苛可以考虑在文本进入 Paragraph 之前用一个简单的正则把中文标点前面合并到上一行末尾或者在断行逻辑里做特殊字符处理。这不是 ReportLab 的强项提前知道能省去很多无用功。6. 技巧五字体嵌入与文件体积控制别等换台电脑才发现字体丢了6.1 TTFont 注册的字体默认会嵌入 PDF有些人在本地打开 PDF 没问题发给同事后同事那边打开全是乱码或者被替换成了别的字体。原因通常是把字体嵌入关掉了或者用了某种不嵌入字体的配置。ReportLab 用TTFont注册的字体默认会嵌入到 PDF 文件里。所以只要你是按前面几节的方式注册字体生成的 PDF 换电脑打开是安全的。反过来如果你发现 PDF 打开后字体被静默替换先回代码里查fontName是不是写错了或者字体根本没有注册成功。字体缺失时 ReportLab 不会立刻崩溃可能只是渲染成备用字体这个隐蔽性很强。6.2 字体文件太大时关注子集嵌入和实际体积中文字体文件普遍不小。一个字体文件可能 10MB 以上嵌入到 PDF 里会拖大文件体积。ReportLab 对 TTFont 的处理会把实际用到的字形做子集化只把文本里出现的字符嵌进去所以通常情况下 PDF 里嵌入的中文字体体积比原始字体文件小很多。但如果你生成一个包含数万字的大型资料文档用到的字形几乎覆盖全表嵌入体积自然就上来了。这时候可以从字体选型入手换用体积更小的字体文件比如裁剪后的精简字体或者把文档拆成多个 PDF减少单文件嵌入规模。我在实际项目中见过一个 50MB 的 PDF定位后发现里面嵌了一整套 20MB 的黑体。换成按需使用的精简 TTF 后文件直接降到 8MB。生成前看一眼字体文件大小比生成后反复压缩 PDF 高效得多。6.3 快速检查嵌入结果生成 PDF 之后怎么确认字体真的嵌入进去了用 PDF 阅读器的“字体”属性查看能看到字体名称和嵌入状态。用命令行工具pdffonts检查在 Linux/macOS 下很方便Windows 也可以用一些开源部署。命令行输出类似name type encoding emb sub uni object ID ------------------------------------ ----------------- -------------- --- --- --- --------- MSYH TrueType WinAnsi yes yes no 4 0 KBAGLUSimSun TrueType WinAnsi yes yes yes 6 0重点是emb一栏必须是yes。如果显示no说明字体没嵌入分发时大概率出问题。另外pdffonts里如果字体名前面有KBAGLU这种前缀说明字体已经在 PDF 内部做了子集化只保留用到的字形。这是正常现象不是字体坏了。7. 给第一次上手的人一个最小可行方案如果你现在就要在项目里用 ReportLab 输出中文 PDF但又没时间细看原理我直接给一套最小组合准备一个 TTF 或 TTC 中文字体文件建议用 Windows 自带的simhei.ttf或者思源黑体路径单独放配置里。用pdfmetrics.registerFont(TTFont(...))注册TTC 文件记得写subfontIndex。正文一律用ParagraphParagraphStyle不要用drawString画长文本。中英文混排用font标签切换字体文本里的、、先转义。设好firstLineIndent、leading、alignment然后生成 PDF 后用pdffonts确认字体嵌入状态。这套组合支撑过我在两个业务系统里的 PDF 导出模块——一个生成销售订单一个生成数据分析报告。订单模块里中英混排的商品名特别多分析报告里则是大段大段的中文结论文本。两类场景都验证过上面的方法稳定运行了很长时间。最后再分享一个经验ReportLab 的字体问题不像其他 Python 库的报错那么直观很多子问题都是“生成成功但视觉效果不对”。所以排查时别急着改业务代码先把自己当场当成 PDF 阅读器去查字体。字体这关过去中文 PDF 的 80% 问题都解决了。剩下 20% 的排版精修按前面每个参数逐步调就行。