Java HTML转PDF在信创环境下中文乱码如何解决？

Question

在信创环境下，使用Java将HTML转为PDF时，常因系统缺少中文字体或字体未正确嵌入导致中文乱码。尤其在国产操作系统（如统信UOS、麒麟）中，默认不包含Windows常用字体（如宋体、微软雅黑），致使iText、Flying Saucer等库无法正常渲染中文。如何在无网络环境下，通过自定义字体嵌入解决HTML转PDF过程中的中文显示问题，成为信创适配中的典型技术难题。

Answer 1

信创环境下Java实现HTML转PDF的中文字体嵌入解决方案

1. 问题背景与挑战分析

在信创（信息技术应用创新）生态逐步推广的背景下，越来越多的应用需要在国产操作系统如统信UOS、银河麒麟等环境中运行。这些系统通常基于Linux内核，且默认未预装Windows常见的中文字体（如宋体、微软雅黑、黑体等）。当使用Java技术栈将HTML内容转换为PDF时，常依赖于iText、Flying Saucer（即xhtmlrenderer）、OpenPDF等开源库，而这些库在渲染过程中若无法找到合适的中文字体，会导致中文字符显示为方框或乱码。

尤其在无网络环境的封闭部署场景中，无法通过在线字体服务动态加载资源，进一步加剧了字体缺失问题。因此，如何在不依赖外部网络的前提下，通过自定义字体文件嵌入的方式保障中文正常显示，成为信创适配中的关键技术难点。

2. 常见技术方案对比

方案	核心库	是否支持字体嵌入	信创兼容性	适用场景
iText + XML Worker	iText 5 / iText 7	支持（需手动注册）	高（可离线）	结构化HTML转PDF
Flying Saucer (xhtmlrenderer)	Core Render + Batik	支持（通过FontResolver）	中（依赖AWT字体配置）	轻量级HTML渲染
WKHtmlToPDF（JNI调用）	webkit引擎封装	依赖系统字体	低（需安装二进制）	复杂页面布局
Thymeleaf + PDFBox + HTML解析器	Apache PDFBox	支持（编程控制）	高（完全Java实现）	定制化生成

3. 解决思路演进：从浅层修复到深层适配

1. 尝试使用系统已安装字体路径进行探测，但发现UOS/麒麟系统缺少常见ttf字体文件。
2. 引入开源中文字体（如思源黑体、文泉驿微米黑）并打包至项目resources目录。
3. 在代码中通过FontProgramFactory或ITextFontResolver注册字体流。
4. 设置CSS样式强制指定font-family，确保HTML标签匹配嵌入字体。
5. 对Base64编码字体进行内联处理，避免路径依赖。
6. 构建统一字体资源管理模块，支持多字体回退机制。
7. 利用缓存机制提升重复转换性能。
8. 封装成独立Service组件，供微服务调用。
9. 增加字体授权合规检查，满足信创安全审计要求。
10. 设计自动化测试用例验证不同HTML片段的渲染效果。

4. 核心实现代码示例（基于iText 7）

public byte[] htmlToPdfWithChineseFont(String htmlContent) throws IOException {
    ByteArrayOutputStream pdfStream = new ByteArrayOutputStream();
    PdfWriter writer = new PdfWriter(pdfStream);
    PdfDocument pdfDoc = new PdfDocument(writer);
    Document document = new Document(pdfDoc);

    // 加载自定义中文字体（如思源黑体）
    String fontPath = "fonts/SimSun.ttf"; // 放置于resources/fonts/
    FontProgram fontProgram = FontProgramFactory.createFont(fontPath);
    PdfFont chineseFont = PdfFontFactory.createFont(fontProgram, PdfEncodings.IDENTITY_H, true);

    // 注册字体到全局渲染上下文
    DefaultCssUpdater cssUpdater = new DefaultCssUpdater();
    cssUpdater.getCssContext().put("body", "font-family: 'SimSun';");

    // 使用HTMLWorker解析HTML
    HtmlConverter.convertToDocument(
        new StringReader(htmlContent),
        pdfDoc,
        new ConverterProperties()
            .setBaseUri(null)
            .setFontProvider(new SimpleFontProvider(chineseFont))
    );

    document.close();
    return pdfStream.toByteArray();
}

5. 字体嵌入流程图（Mermaid格式）

graph TD
            A[开始HTML转PDF] --> B{是否存在中文字体?}
            B -- 否 --> C[加载内置TTF字体流]
            B -- 是 --> D[使用已有字体]
            C --> E[创建PdfFont对象并嵌入]
            E --> F[设置CSS font-family指向该字体]
            F --> G[解析HTML内容]
            G --> H[生成PDF字节流]
            H --> I[输出结果]
            I --> J[结束]

6. 实践建议与最佳实践

• 优先选择开源且可商用的中文字体，如Adobe Source Han Sans（思源黑体）或文泉驿微米黑。
• 将字体文件置于src/main/resources/fonts/目录下，通过ClassPathResource读取，保证跨平台一致性。
• 使用PdfEncodings.IDENTITY_H编码方式以支持中文字符集（CJK）。
• 在HTML中显式声明style="font-family: 'SimSun'"，避免浏览器默认字体干扰。
• 对生成的PDF进行视觉回归测试，确保段落、表格、标题等元素排版正确。
• 考虑字体子集化（subset=true），减小PDF体积。
• 在Docker镜像或国产OS部署包中预置字体资源，形成标准化交付物。
• 建立字体使用台账，符合信创环境下的知识产权合规要求。