当前位置：首页 > news >正文

从乱码到清晰：一位开发者与iText7中文PDF的三年斗争史

news 2026/8/19 14:53:37

从乱码到清晰：一位开发者与iText7中文PDF的三年斗争史

【免费下载链接】itext7-chinese-font项目地址: https://gitcode.com/gh_mirrors/it/itext7-chinese-font

"为什么我的PDF中文又变成方块了？" 这可能是每个Java开发者在处理中文PDF时都会发出的灵魂拷问。今天，我要分享一个真实的故事，以及我们如何最终找到了完美的解决方案。

故事开始：那个令人绝望的周一早晨

三年前，我在一家金融科技公司负责报表系统。客户要求生成包含中文财务数据的PDF报表，听起来很简单，对吧？我自信满满地选择了当时最流行的iText7库，写了几行代码，生成了第一份测试报告。

打开PDF的那一刻，我愣住了——所有的中文都变成了"□□□□□□"。

"这不可能，"我自言自语，"我明明设置了UTF-8编码！"

接下来的48小时，我尝试了所有我能找到的方法：更换字体、调整编码、甚至重写了整个渲染逻辑。但问题依然存在。客户在催，老板在问，而我只能看着满屏的方块发呆。

第一次突破：发现问题的本质

经过三天不眠不休的调试，我终于明白了问题的根源：PDF不像HTML或Word，它需要字体文件中的字形数据才能正确显示文字。这就像你要打印一份中文文档，但打印机里只有英文字母的模具。

iText7默认使用Helvetica等英文字体，这些字体根本不包含中文字形。当系统尝试渲染中文时，它找不到对应的字形，只能用方块或空白代替。

关键发现：PDF的字体嵌入机制与操作系统字体无关，必须将中文字体文件嵌入到PDF文档中。

寻找解决方案：从失败到成功的探索之路

尝试1：系统字体依赖（失败）

// 最初的天真想法 PdfFont font = PdfFontFactory.createFont("Microsoft YaHei", PdfEncodings.IDENTITY_H);

❌问题：在不同操作系统上字体名称不同，且无法保证目标系统安装了相同字体

尝试2：字体文件路径硬编码（半成功）

// 稍微进步一点 PdfFont font = PdfFontFactory.createFont("C:/Windows/Fonts/msyh.ttf", PdfEncodings.IDENTITY_H);

⚠️风险：部署环境可能没有这个字体文件，路径在不同系统上完全不同

尝试3：资源文件嵌入（终于成功！）

// 正确的做法 InputStream fontStream = getClass().getResourceAsStream("/fonts/SourceHanSansSC-Regular.ttf"); PdfFont font = PdfFontFactory.createFont(fontStream, PdfEncodings.IDENTITY_H, true);

✅优势：字体文件随应用一起打包，不依赖系统环境

实战：iText7中文字体解决方案全解析

第一步：准备你的字体武器库

你需要收集高质量的中文字体文件。在我们的项目中，我们选择了三种字体：

阿里巴巴普惠体- 现代商务风格
思源黑体- 简洁现代风格
思源宋体- 传统正式风格

将这些字体文件放在项目的资源目录中：

src/main/resources/fonts/ ├── AlibabaPuHuiTi-2-45-Light.ttf ├── AlibabaPuHuiTi-2-85-Bold.ttf ├── SourceHanSansSC-ExtraLight.otf ├── SourceHanSansSC-Medium.otf ├── SourceHanSerifSC-ExtraLight.otf └── SourceHanSerifSC-Medium.otf

#实操标签：字体文件准备 #资源目录结构

第二步：创建字体管理工厂

与其每次生成PDF都重新加载字体，不如创建一个字体工厂来统一管理：

public class ChineseFontFactory { private static final Map<String, PdfFont> fontCache = new HashMap<>(); public static PdfFont getFont(String fontName, boolean bold) { String key = fontName + "_" + bold; if (!fontCache.containsKey(key)) { String fontPath = getFontPath(fontName, bold); try (InputStream is = ChineseFontFactory.class.getResourceAsStream(fontPath)) { PdfFont font = PdfFontFactory.createFont(is, PdfEncodings.IDENTITY_H, true); fontCache.put(key, font); return font; } catch (IOException e) { throw new RuntimeException("字体加载失败: " + fontPath, e); } } return fontCache.get(key); } private static String getFontPath(String fontName, boolean bold) { switch (fontName) { case "AlibabaPuHuiTi": return bold ? "/fonts/AlibabaPuHuiTi-2-85-Bold.ttf" : "/fonts/AlibabaPuHuiTi-2-45-Light.ttf"; case "SourceHanSans": return bold ? "/fonts/SourceHanSansSC-Medium.otf" : "/fonts/SourceHanSansSC-ExtraLight.otf"; case "SourceHanSerif": return bold ? "/fonts/SourceHanSerifSC-Medium.otf" : "/fonts/SourceHanSerifSC-ExtraLight.otf"; default: return "/fonts/SourceHanSansSC-ExtraLight.otf"; } } }

#实操标签：字体工厂模式 #资源缓存优化

第三步：HTML到PDF的完美转换

对于HTML内容转换，iText7提供了强大的HtmlConverter。关键在于正确配置ConverterProperties：

public class PDFGenerator { public static byte[] generatePDF(String htmlContent, String fontFamily) { try { // 创建字体提供器 FontProvider fontProvider = new FontProvider(); fontProvider.addFont(getFontData(fontFamily, false)); fontProvider.addFont(getFontData(fontFamily, true)); fontProvider.addStandardPdfFonts(); // 配置转换属性 ConverterProperties properties = new ConverterProperties(); properties.setFontProvider(fontProvider); properties.setCharset("UTF-8"); // 执行转换 ByteArrayOutputStream outputStream = new ByteArrayOutputStream(); HtmlConverter.convertToPdf(htmlContent, outputStream, properties); return outputStream.toByteArray(); } catch (Exception e) { throw new RuntimeException("PDF生成失败", e); } } private static byte[] getFontData(String fontFamily, boolean bold) throws IOException { // 从资源文件读取字体数据 String resourcePath = getFontResourcePath(fontFamily, bold); try (InputStream is = PDFGenerator.class.getResourceAsStream(resourcePath)) { return IOUtils.toByteArray(is); } } }

#实操标签：HTML转PDF配置 #字符编码设置

效果展示：中文PDF渲染对比

让我们看看正确配置后的效果：

图：三种字体（阿里巴巴普惠体、思源黑体、思源宋体）在PDF中的渲染效果对比，展示了英文、中文简体和中文繁体在不同样式下的完美显示

从图中可以看到：

英文部分：标准的"The quick brown fox jumps over a lazy dog"测试句
中文简体："那只敏捷的棕色狐狸跳过了一只懒狗"在不同字号和字重下的表现
中文繁体：繁体版本的正确渲染
特殊符号：各种符号的完整支持

快速上手：5分钟搞定中文PDF

如果你现在就想尝试，这里是完整的快速入门指南：

1. 克隆项目并查看示例

git clone https://gitcode.com/gh_mirrors/it/itext7-chinese-font cd itext7-chinese-font

2. 运行示例代码

mvn compile exec:java -Dexec.mainClass="com.starxg.itext7chinesefont.IText7ChineseFont"

3. 查看生成结果

程序会生成三个PDF文件，分别展示不同字体的效果。打开这些文件，你会看到中文完美显示。

4. 集成到你的项目

将src/main/resources/fonts/目录下的字体文件复制到你的项目中，然后使用我们提供的工具类即可。

⚠️重要提示：确保你的Maven依赖包含iText7核心库和HTML转换模块：

<dependency> <groupId>com.itextpdf</groupId> <artifactId>itext7-core</artifactId> <version>7.2.1</version> </dependency> <dependency> <groupId>com.itextpdf</groupId> <artifactId>html2pdf</artifactId> <version>3.0.4</version> </dependency>