Java读写PDF时中文乱码如何解决？

Question

在使用Java生成或读取PDF文件时，常因未正确嵌入中文字体或未设置合适的编码导致中文显示为乱码。典型问题出现在iText、Apache PDFBox等库中，系统默认字体不支持中文字符集（如GB2312、UTF-8），导致文本输出异常。如何通过加载并嵌入支持中文的TrueType字体（如SimSun、Microsoft YaHei）并显式指定编码格式，确保PDF中中文正确渲染，是开发中常见的技术难题。

Answer 1

一、问题背景与常见现象

在Java应用中生成或读取PDF文档时，中文乱码是一个长期存在的痛点。尤其是在使用iText、Apache PDFBox等主流PDF处理库时，开发者常常遇到中文字符无法正常显示的问题。

根本原因在于：大多数PDF生成库默认使用的字体（如Helvetica、Times-Roman）仅支持ASCII字符集，不包含中文所需的字形数据。当系统尝试渲染UTF-8或GB2312编码的中文文本时，若未显式指定支持中文的TrueType字体（如SimSun、Microsoft YaHei），则会以“□”或乱码形式呈现。

此问题在跨平台部署中尤为突出——开发环境可能因本地已安装中文字体而表现正常，但生产服务器（如Linux无GUI环境）往往缺失相应字体资源，导致线上故障。

二、技术原理剖析

PDF文件中的文本渲染依赖于字体嵌入机制。根据PDF规范，若使用了非标准字体（非Base 14 Fonts），必须将该字体子集或完整字体嵌入到PDF中，否则阅读器将尝试用替代字体渲染，极易造成乱码。

Java中处理PDF时涉及的关键环节包括：

1. 字符编码解析（如InputStreamReader设置UTF-8）
2. 字体加载与注册（通过FontProvider或PDFFont加载TTF文件）
3. 字体嵌入选项配置（是否嵌入全部字形或仅子集）
4. 内容写入时绑定字体实例

若任一环节未正确处理中文编码或字体路径，都将引发最终输出异常。

三、主流库解决方案对比

库名称	字体加载方式	编码处理建议	是否支持自动嵌入	典型API示例
iText 7	via FontProgramFactory.createFont()	需确保String为UTF-8解码	是（需手动启用）	PdfFont font = PdfFontFactory.createFont("simsun.ttc,0", PdfEncodings.IDENTITY_H);
Apache PDFBox	PDType0Font.load()	内容流须用UTF-8编码字符串	是（推荐嵌入）	PDType0Font font = PDType0Font.load(document, new FileInputStream("msyh.ttf"));
Flying Saucer (XMLWorker)	通过ITextRenderer注册字体	CSS中指定font-family并映射TTF	支持自定义FontResolver	使用IRenderer注入字体映射

四、iText 7 中文字体嵌入实战代码

// 使用 iText 7 嵌入 SimSun 字体并输出中文
public void generateChinesePdf(String outputPath) throws IOException {
    PdfWriter writer = new PdfWriter(outputPath);
    PdfDocument pdf = new PdfDocument(writer);
    Document document = new Document(pdf);

    // 加载宋体（支持中文）
    PdfFont chineseFont = PdfFontFactory.createFont(
        "C:/Windows/Fonts/simsun.ttc,0", // TTF路径，注意ttc需指定索引
        PdfEncodings.IDENTITY_H,          // 支持Unicode双字节字符
        true                              // 嵌入字体
    );

    // 设置字体并写入中文
    document.add(new Paragraph("你好，世界！欢迎使用iText生成PDF。")
        .setFont(chineseFont)
        .setFontSize(12));

    document.close();
}

关键点说明：IDENTITY_H编码用于支持CJK统一汉字，避免使用WinAnsiEncoding等不兼容编码；true参数确保字体嵌入PDF文件内部。

五、Apache PDFBox 实现方案

// 使用 PDFBox 写入带中文字体的PDF
public void createPdfWithChinese(String outputPath) throws IOException {
    PDDocument document = new PDDocument();
    PDPage page = new PDPage();
    document.addPage(page);

    // 加载微软雅黑字体
    try (FileInputStream fis = new FileInputStream("msyh.ttf")) {
        PDType0Font font = PDType0Font.load(document, fis);

        PDPageContentStream contentStream = new PDPageContentStream(document, page);
        contentStream.beginText();
        contentStream.setFont(font, 12);
        contentStream.newLineAtOffset(100, 700);
        
        // 必须确保字符串来自UTF-8源
        contentStream.showText("这是一个测试：中文显示正常吗？");
        contentStream.endText();
        contentStream.close();
    }

    document.save(outputPath);
    document.close();
}

注意：PDFBox要求外部TTF文件可访问，且建议在构建时打包字体资源至JAR内，并通过getClass().getResourceAsStream()读取。

六、系统级优化与最佳实践流程图

graph TD
            A[开始生成PDF] --> B{是否包含中文?}
            B -- 是 --> C[加载支持中文的TTF字体]
            B -- 否 --> D[使用默认字体]
            C --> E[检查字体文件是否存在]
            E -- 存在 --> F[创建字体对象并启用嵌入]
            E -- 不存在 --> G[抛出异常或回退到备用字体]
            F --> H[设置文本编码为UTF-8]
            H --> I[将中文字符串写入内容流]
            I --> J[关闭文档并保存]
            J --> K[验证PDF中文字渲染效果]

七、高级注意事项与调试技巧

• 字体子集化：为减小文件体积，可选择只嵌入实际使用的字符子集，但需确保所有中文字符被覆盖。
• 许可证合规性：商业字体（如微软雅黑）受版权保护，分发PDF时需确认是否允许嵌入。
• 跨平台路径兼容：避免硬编码C:\Windows\Fonts\...，应将字体打包进resources目录。
• 编码一致性：从数据库、网络请求获取的中文数据应统一转换为UTF-8再传入PDF引擎。
• 日志监控：捕获NoSuchElementException或IOException等字体加载异常。
• 测试策略：在无GUI的Linux容器中进行自动化测试，模拟真实部署环境。
• 性能考量：频繁创建PDF时可缓存已加载的PdfFont实例以提升效率。
• 字体回退机制：实现多级字体fallback，如SimSun → Noto Sans CJK SC → 默认字体。
• PDF/A合规需求：归档类PDF需强制嵌入所有字体，符合ISO 19005标准。
• 动态字体选择：根据用户语言偏好切换字体族（简体/繁体/日文）。