Python PyMuPDF 中文乱码如何解决？

Question

在使用 Python 的 PyMuPDF（fitz）库向 PDF 添加中文文本时，常出现中文乱码或方框问号等问题。这是因为 PyMuPDF 默认不支持中文字体，且未嵌入合适的 TTF 字体文件。即使正确调用 `insert_text()` 方法，若未指定支持中文的字体（如 SimSun、Microsoft YaHei 等），系统将回退到无中文字符集的默认字体，导致渲染失败。如何通过加载外部中文字体文件并正确传入字体参数来解决此问题，是开发者常遇到的技术难点。

Answer 1

一、问题背景与现象分析

在使用 Python 的 PyMuPDF（即 fitz）库向 PDF 文档中插入文本时，开发者普遍遇到一个棘手的问题：中文字符显示为乱码或呈现为方框（□）甚至问号（？）。这种现象并非代码逻辑错误所致，而是由于 PyMuPDF 默认使用的字体不包含中文字符集。

PyMuPDF 内置支持的字体如 Helvetica、Courier 等均属于西方字符编码体系（如 Latin-1），无法映射 Unicode 中的汉字区段（U+4E00–U+9FFF）。当调用 page.insert_text() 方法插入中文但未显式指定中文字体时，系统会回退到默认字体，导致渲染失败。

以下是一个典型的错误示例：

import fitz

doc = fitz.open()
page = doc.new_page()
page.insert_text((72, 72), "你好，世界！", fontsize=12)
doc.save("output.pdf")
doc.close()

上述代码虽然语法正确，但在大多数环境下输出的 PDF 中，“你好，世界！”将显示为方框或乱码。

二、技术原理与核心机制

要深入理解该问题的本质，需掌握以下几个关键点：

1. 字体嵌入机制：PDF 标准要求所有非标准字体必须以子集形式嵌入文档，否则依赖阅读器本地字体。PyMuPDF 允许通过 fontfile 参数加载外部 TTF 或 OTF 字体文件并自动嵌入。
2. Unicode 支持：现代 PDF 支持 UTF-8 编码文本，但前提是所用字体包含对应的字形（glyphs）。
3. 字体命名与路径：PyMuPDF 使用 fontname 来标识字体，若使用自定义字体文件，必须同时提供 fontfile 路径。

下表列出了常用中文字体及其在 Windows 和 Linux 下的典型路径：

字体名称	Windows 路径	Linux 常见路径	文件名
SimSun（宋体）	C:\Windows\Fonts\simsun.ttc	/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc	simsun.ttc / simsun.ttf
Microsoft YaHei（微软雅黑）	C:\Windows\Fonts\msyh.ttc	-	msyh.ttc
SimHei（黑体）	C:\Windows\Fonts\simhei.ttf	/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf	simhei.ttf
WenQuanYi Zen Hei（文泉驿正黑）	-	/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc	wqy-zenhei.ttc

三、解决方案与实现路径

解决中文乱码的核心在于显式加载支持中文的字体文件，并通过 insert_text() 的 fontname 和 fontfile 参数传入。

以下是完整且可运行的修复方案：

import fitz

def add_chinese_text(pdf_path, output_path, text, pos, font_path=None):
    doc = fitz.open(pdf_path) if pdf_path else fitz.Document()
    page = doc.new_page() if not doc.page_count else doc[0]

    # 指定中文字体文件路径
    if font_path is None:
        font_path = "C:/Windows/Fonts/simsun.ttc"  # 可替换为 msyh.ttc 等

    try:
        # 插入中文文本，指定字体文件
        page.insert_text(
            pos,
            text,
            fontsize=12,
            fontname="china",  # 自定义字体名
            fontfile=font_path,  # 加载外部字体
            encoding=fitz.TEXT_ENCODING_UNICODE
        )
    except RuntimeError as e:
        print(f"字体加载失败: {e}")
        print("请确认字体文件存在且支持中文字符")

    doc.save(output_path)
    doc.close()

# 使用示例
add_chinese_text(None, "chinese_output.pdf", "这是一个测试：PyMuPDF 添加中文", (72, 72), "C:/Windows/Fonts/simsun.ttc")

注意：fontname 是用户自定义标识符，只要唯一即可；fontfile 必须指向有效的 TTF/OTF 文件。

四、高级优化与工程实践

在企业级应用中，还需考虑跨平台兼容性、字体缓存、异常处理等工程化问题。推荐采用如下策略：

• 封装字体管理类，统一管理常用中文字体路径。
• 使用 os.path.exists() 验证字体文件是否存在。
• 对 TTC（TrueType Collection）字体，可通过索引选择具体子字体（如宋体常规体）。
• 批量插入时预加载字体以提升性能。

以下为增强版字体管理模块示意图：

graph TD
            A[开始插入中文] --> B{是否已注册字体?}
            B -- 是 --> C[使用缓存 fontname]
            B -- 否 --> D[加载字体文件]
            D --> E[检查文件可读性]
            E --> F[调用 insert_text 并传入 fontfile]
            F --> G[成功插入]
            E --> H[抛出异常并记录日志]

五、常见误区与调试技巧

尽管原理清晰，但在实际开发中仍容易陷入以下误区：

1. 误以为系统字体名（如 "SimSun"）可直接用于 fontname —— 实际上 PyMuPDF 不识别系统字体名，必须通过 fontfile 显式加载。
2. 忽略 encoding=fitz.TEXT_ENCODING_UNICODE 参数，在旧版本中可能导致编码错误。
3. 使用压缩率过高的字体子集导致某些生僻字缺失。
4. 在 Docker 或 CI 环境中缺少中文字体文件，导致部署失败。

调试建议：

• 打印 fitz.get_font_list() 查看当前可用字体。
• 使用 PDF 阅读器的“字体信息”功能验证目标字体是否已嵌入。
• 在 Linux 上可通过 fc-list :lang=zh 查询系统中文字体。