ReportLab生成PDF中文乱码如何解决？

Question

在使用ReportLab生成PDF时，常因未正确注册中文字体导致中文乱码。默认情况下，ReportLab不支持Unicode中文字符，直接输出中文会显示为方框或问号。解决方法是通过`pdfmetrics`和`ttfonts`模块注册本地支持中文的TrueType字体（如SimSun、Microsoft YaHei），并将其添加至`canvas`或`Paragraph`样式中。同时需确保字体文件存在且路径正确，避免因字体缺失引发异常。此外，文档编码应统一为UTF-8。

Answer 1

一、问题背景与现象分析

在使用ReportLab生成PDF文档时，中文乱码是一个常见且棘手的问题。默认情况下，ReportLab仅支持基本的拉丁字符集（如Helvetica、Times-Roman等），并不包含对Unicode中文字符的原生支持。当开发者尝试直接输出中文字符串时，往往会出现方框（□）、问号（？）或空白字符，严重影响文档可读性。

• 典型错误场景：调用canvas.drawString(x, y, "你好，世界")时出现乱码
• 根本原因：未注册支持中文的TrueType字体
• 系统依赖：操作系统是否安装了指定中文字体（如SimSun、Microsoft YaHei）
• 编码隐患：Python源文件或数据流未使用UTF-8编码

二、技术原理与核心机制

ReportLab通过reportlab.pdfbase.pdfmetrics模块管理字体注册，而reportlab.pdfbase.ttfonts用于加载本地TTF字体文件。要实现中文显示，必须将外部中文字体映射为PDF可用的字体族，并在绘图上下文或样式表中显式引用。

模块	功能说明
ttfonts.TTFont	加载本地TrueType字体文件
pdfmetrics.registerFont	将字体注册到全局字体池
canvas.setFont	在Canvas中切换当前字体
ParagraphStyle.fontName	为富文本段落指定注册后的字体名

三、解决方案实施路径

解决中文乱码需遵循以下步骤：

1. 确认目标环境中存在支持中文的TTF字体文件（如simsun.ttc或msyh.ttf）
2. 使用TTFont类加载字体并注册唯一字体名称
3. 在Canvas或Paragraph对象中调用对应字体名
4. 确保所有输入文本以UTF-8编码处理
5. 捕获可能的KeyError或RuntimeError异常，提示字体缺失

from reportlab.pdfbase import pdfmetrics, ttfonts
from reportlab.platypus import Paragraph
from reportlab.lib.styles import getSampleStyleSheet

# 注册宋体（SimSun）
try:
    pdfmetrics.registerFont(ttfonts.TTFont('SimSun', 'simsun.ttc'))
    pdfmetrics.registerFont(ttfonts.TTFont('MicrosoftYaHei', 'msyh.ttf'))
except IOError:
    raise RuntimeError("中文字体文件未找到，请检查路径")

styles = getSampleStyleSheet()
style_CN = styles['Normal']
style_CN.fontName = 'SimSun'
para = Paragraph("这是一段中文内容", style_CN)

四、进阶实践与跨平台考量

在企业级应用中，需考虑不同操作系统间的字体路径差异。Windows通常位于C:\Windows\Fonts\，Linux可能需手动安装fonts-noto-cjk包，macOS则存放于/System/Library/Fonts/或~/Library/Fonts/。

graph TD A[开始生成PDF] --> B{是否含中文?} B -->|是| C[加载中文字体文件] B -->|否| D[使用默认字体] C --> E[注册字体至pdfmetrics] E --> F[设置Canvas或Paragraph字体名] F --> G[输出UTF-8编码文本] G --> H[生成PDF]

建议封装字体注册逻辑为独立模块，支持自动探测系统字体路径：

import os
def get_chinese_font_path():
    paths = [
        '/usr/share/fonts/truetype/noto/NotoSansCJK-Regular.ttc',  # Linux
        'C:/Windows/Fonts/simsun.ttc',                             # Windows
        '/System/Library/Fonts/PingFang.ttc'                       # macOS
    ]
    for p in paths:
        if os.path.exists(p):
            return p
    return None