iTextPDF 5.5.10 PdfStamper 中文不显示？字体嵌入与IDENTITY_H编码实战

1. 问题背景与核心痛点拆解

1.1 这个坑到底卡在哪儿

用 iTextPDF 5.5.10 做 PDF 二次处理的朋友，大概率都碰过这个场景：拿一份现成的 PDF 模板，用PdfStamper往指定位置填数据，英文数字一切正常，一旦塞入中文，要么整段消失，要么变成一堆空白方块，要么干脆抛异常。更让人抓狂的是，同样的字体代码，换成PdfWriter从头生成 PDF 时中文显示得好好的，一换成PdfStamper就翻车。

这不是玄学，也不是 iText 的 bug，而是PdfStamper和PdfWriter在底层处理逻辑上有本质差异。PdfWriter是从零构建文档，字体资源由你完全掌控；而PdfStamper是在已有 PDF 上做增量修改，它需要把新内容“叠加”到原有内容流上，字体资源的注册方式、编码映射、子集化策略都跟从头写完全不是一回事。

这个问题的核心关键词就是：iTextPDF 5.5.10、PdfStamper、中文不显示、字体嵌入、BaseFont。搞明白这几个词之间的关系，问题就解决了一大半。

1.2 谁最容易踩这个坑

我观察下来，这几类开发者最容易中招：

• 做电子合同、电子发票、报表导出功能的 Java 后端开发者，模板 PDF 是设计部门给的，你只负责填数据
• 做 OA 系统、审批流的老项目维护者，项目里锁死了 iText 5.x 版本，没法升级到 7.x
• 刚接触 iText 的新手，照着网上PdfWriter的教程改写成PdfStamper，结果中文直接消失

这个问题的适用范围很明确：只要你用 iText 5.5.10 的PdfStamper往 PDF 里写中文，就一定会遇到。解决它不需要升级版本，也不需要换库，关键是把字体加载和注册的方式改对。

1.3 解决思路总览

整件事的逻辑链条其实不复杂，我用一句话概括：PdfStamper环境下，中文字体必须用BaseFont.createFont以 IDENTITY_H 编码嵌入，再通过FontFactory或直接构造Font对象绑定到Chunk或Phrase上，最后用ColumnText或PdfContentByte写入。

听起来简单，但每一步都有坑。比如字体文件从哪来、编码参数怎么选、字体要不要子集化、ColumnText的坐标系怎么对齐，这些细节决定了你是十分钟搞定还是折腾一整天。接下来我会把这些环节一个个拆开讲透。

2. 核心原理：为什么 PdfStamper 下中文会消失

2.1 PdfWriter 与 PdfStamper 的字体处理差异

要理解问题，先得搞清楚这两个类的工作方式有什么不同。

PdfWriter的工作模式是“白纸作画”。你new Document()的时候，整个 PDF 的页面树、资源字典、字体表都是空的，你往里加什么字体，它就往资源字典里注册什么字体。中文字体你只要用BaseFont.createFont("STSong-Light", "UniGB-UCS2-H", BaseFont.NOT_EMBEDDED)加载，它就能正确写入。

PdfStamper的工作模式是“在已有画作上贴便签”。它读取一个已经存在的 PDF，这个 PDF 有自己的资源字典、字体表、内容流。当你用PdfStamper往页面里写新内容时，iText 需要做两件事：第一，把新内容追加到原有内容流后面；第二，把新用到的字体资源注册到页面的资源字典里。

问题就出在第二步。iText 5.5.10 在处理PdfStamper的字体注册时，如果你用的是默认的FontFactory.getFont()方式，它可能拿不到正确的编码信息，导致中文字符在写入时被当作单字节字符处理，最终在 PDF 里显示为空白或乱码。

2.2 中文字体的编码机制：为什么 IDENTITY_H 是关键

PDF 里的字体编码方式直接决定了字符怎么映射到字形。对于中文这种字符集，常用的编码方案有几种：

PdfStamper场景下，最稳妥的方案是Identity-H。原因在于：Identity-H 是“字形索引”编码，它不依赖字符集映射表，而是直接把每个字符的 Glyph ID 写进内容流。这意味着只要字体文件里有这个字形，它就能正确显示，不受编码表缺失的影响。

而 UniGB-UCS2-H 虽然也能显示中文，但它依赖 iText 内置的 CMap 资源，在某些PdfStamper场景下会因为资源加载路径问题导致映射失败。所以我的建议很明确：用 TrueType 字体文件 + Identity-H 编码，这是最稳的组合。

2.3 字体嵌入与子集化的取舍

字体嵌入是另一个关键决策点。你有两个选择：

• 完全嵌入：把整个字体文件塞进 PDF，文件体积大（中文字体动辄几 MB 到十几 MB），但兼容性最好
• 子集化嵌入：只嵌入用到的字符对应的字形，文件体积小，但需要 iText 正确执行子集化

在PdfStamper场景下，我强烈建议开启子集化。原因很简单：你往模板里填的中文字符通常就那么几十个到几百个，完全嵌入一个 10MB 的字体文件纯属浪费。iText 的BaseFont.createFont方法在embedded参数设为BaseFont.EMBEDDED时，会自动做子集化处理。

但这里有个坑：子集化需要字体文件可读且格式正确。如果你用的是.ttc字体集合文件，iText 5.5.10 对它的支持有限，建议先提取出单个.ttf文件再用。

3. 完整实操方案：从字体准备到中文写入

3.1 字体文件的准备与选择

第一步是搞到一个可用的中文 TrueType 字体文件。你有几个来源：

• 系统自带字体：Windows 下的simsun.ttc、simhei.ttf，Linux 下的wqy-zenhei.ttc
• 开源字体：思源黑体、思源宋体的.ttf或.otf文件
• 商业授权字体：需要确认授权允许嵌入 PDF

我的建议是优先用.ttf格式的字体文件，避免.ttc。因为 iText 5.5.10 对.ttc的支持需要额外指定字体索引，容易出错。如果你手头只有.ttc，可以用字体工具先导出单个字体。

字体文件放哪里也有讲究。放在src/main/resources/fonts/目录下，通过类加载器读取是最稳妥的方式，这样打包成 JAR 后也能正常加载。不要用绝对路径，否则部署到服务器上大概率找不到文件。

// 从 classpath 加载字体文件 InputStream fontStream = getClass().getClassLoader() .getResourceAsStream("fonts/simhei.ttf"); BaseFont baseFont = BaseFont.createFont( "fonts/simhei.ttf", // 字体路径 BaseFont.IDENTITY_H, // 编码方式 BaseFont.EMBEDDED, // 嵌入字体 false, // 不缓存 fontStream, // 字体流 null // 不生成 .notdef 字形 );

这段代码里每个参数都有讲究。IDENTITY_H是编码方式，EMBEDDED表示嵌入字体并子集化，第四个参数false表示不缓存字体（避免内存泄漏），第五个参数是字体输入流，第六个参数null表示不强制生成缺失字形。

3.2 PdfStamper 写入中文的完整代码

下面是一个完整的、可直接复用的代码示例。场景是：读取一个模板 PDF，在指定坐标位置写入中文文本。

import com.itextpdf.text.*; import com.itextpdf.text.pdf.*; import java.io.*; import java.util.HashMap; import java.util.Map; public class PdfStamperChineseDemo { public static void main(String[] args) throws Exception { // 1. 读取模板 PDF PdfReader reader = new PdfReader("template.pdf"); // 2. 创建输出流 OutputStream os = new FileOutputStream("output.pdf"); // 3. 创建 PdfStamper PdfStamper stamper = new PdfStamper(reader, os); // 4. 加载中文字体 BaseFont baseFont = BaseFont.createFont( "fonts/simhei.ttf", BaseFont.IDENTITY_H, BaseFont.EMBEDDED ); // 5. 创建字体对象，指定大小 Font chineseFont = new Font(baseFont, 12, Font.NORMAL, BaseColor.BLACK); // 6. 获取第一页的内容层 PdfContentByte content = stamper.getOverContent(1); // 7. 使用 ColumnText 写入中文 ColumnText columnText = new ColumnText(content); columnText.setSimpleColumn( 100, // 左下角 x 700, // 左下角 y 500, // 右上角 x 750, // 右上角 y 15, // 行距 Element.ALIGN_LEFT ); // 8. 构造段落 Paragraph paragraph = new Paragraph("这是一段中文测试文本", chineseFont); columnText.addElement(paragraph); columnText.go(); // 9. 关闭 stamper stamper.close(); reader.close(); os.close(); } }

这段代码的核心在于第 4 步和第 7 步。第 4 步用BaseFont.createFont直接加载字体文件，而不是用FontFactory.getFont，这是避免中文不显示的关键。第 7 步用ColumnText而不是直接content.showTextAligned，因为ColumnText能更好地处理段落排版和自动换行。

3.3 坐标定位与对齐的实操技巧

ColumnText.setSimpleColumn的坐标系统是 PDF 标准坐标系：原点在页面左下角，x 向右递增，y 向上递增。这跟很多 UI 框架的左上角原点不一样，新手容易搞反。

我一般用这个公式来定位：

• 左下角 x = 左边距
• 左下角 y = 页面高度 - 上边距 - 文本块高度
• 右上角 x = 页面宽度 - 右边距
• 右上角 y = 页面高度 - 上边距

如果你不确定页面尺寸，可以用reader.getPageSize(1)获取：

Rectangle pageSize = reader.getPageSize(1); float pageWidth = pageSize.getWidth(); float pageHeight = pageSize.getHeight();

还有一个实用技巧：如果你需要精确定位到某个已有字段的位置，可以先用 PDF 编辑工具查看目标坐标，然后在代码里硬编码。但要注意，不同 PDF 阅读器显示的坐标可能有细微差异，建议留 2-3 个点的余量。

注意：ColumnText的setSimpleColumn方法有多个重载版本，参数顺序容易记混。建议用带leading和alignment的完整版本，避免默认值不符合预期。

4. 常见问题排查与避坑指南

4.1 中文显示为空白方块

这是最常见的症状。原因通常有三个：

原因一：字体没有正确嵌入。检查BaseFont.createFont的第三个参数是否设为BaseFont.EMBEDDED。如果设为BaseFont.NOT_EMBEDDED，iText 会假设阅读器本地有这个字体，但大多数阅读器并没有，所以显示为方块。

原因二：编码方式不对。如果你用的是BaseFont.WINANSI或BaseFont.CP1252，中文字符会被过滤掉。必须用BaseFont.IDENTITY_H。

原因三：字体文件本身不包含中文字形。有些英文字体文件虽然扩展名是.ttf，但里面根本没有中文字形。用字体查看工具确认一下。

4.2 中文显示为乱码

乱码和方块是两回事。乱码说明字符被写入了，但编码映射错了。这种情况通常发生在你用了UniGB-UCS2-H编码但 iText 找不到对应的 CMap 文件时。

解决方案很简单：换成IDENTITY_H。如果因为某些原因必须用UniGB-UCS2-H，你需要确保iTextAsian.jar在 classpath 里。但在PdfStamper场景下，我还是推荐IDENTITY_H，省事且稳定。

4.3 抛出 FontNotFoundException

这个异常说明 iText 找不到你指定的字体文件。排查步骤：

1. 确认字体文件路径是否正确。如果用 classpath 路径，确认文件在resources目录下且打包后存在于 JAR 中。
2. 确认字体文件格式是否被 iText 支持。iText 5.5.10 支持.ttf和.otf，对.ttc支持有限。
3. 确认文件读取权限。如果用绝对路径，确认运行用户有读权限。

4.4 文件体积异常增大

如果你发现生成的 PDF 比模板大了好几 MB，说明字体被完全嵌入了，没有做子集化。检查BaseFont.createFont的embedded参数是否设为BaseFont.EMBEDDED。如果已经是EMBEDDED但体积还是大，可能是字体文件本身太大，考虑换一个更精简的字体。

4.5 多页 PDF 只有第一页显示中文

这个问题通常是因为你只对第一页调用了getOverContent(1)。如果模板有多页，你需要对每一页都执行写入操作：

int pageCount = reader.getNumberOfPages(); for (int i = 1; i <= pageCount; i++) { PdfContentByte content = stamper.getOverContent(i); // 写入逻辑 }

但要注意，ColumnText对象不能跨页复用，每页都需要新建一个。

4.6 常见问题速查表

5. 进阶技巧与性能优化

5.1 字体缓存与复用

如果你需要在一次请求中往多个 PDF 写入中文，每次都BaseFont.createFont会很慢。可以把BaseFont对象缓存起来复用：

public class FontCache { private static final Map<String, BaseFont> cache = new HashMap<>(); public static BaseFont getFont(String fontPath) throws Exception { if (!cache.containsKey(fontPath)) { BaseFont baseFont = BaseFont.createFont( fontPath, BaseFont.IDENTITY_H, BaseFont.EMBEDDED ); cache.put(fontPath, baseFont); } return cache.get(fontPath); } }

但要注意，BaseFont对象不是线程安全的，多线程环境下需要加锁或使用ThreadLocal。

5.2 使用 ColumnText 处理复杂排版

ColumnText不仅能写单行文本，还能处理多段落、自动换行、对齐方式等复杂排版。如果你需要在一个区域内写入多段中文，可以这样操作：

ColumnText columnText = new ColumnText(content); columnText.setSimpleColumn(50, 50, 500, 700); Paragraph p1 = new Paragraph("第一段中文内容", chineseFont); Paragraph p2 = new Paragraph("第二段中文内容", chineseFont); p2.setSpacingBefore(10); columnText.addElement(p1); columnText.addElement(p2); columnText.go();

ColumnText会自动处理换行和段落间距，比手动计算坐标方便得多。

5.3 混合中英文的字体策略

如果你的文本是中英文混合，用一个中文字体就够了，因为中文字体通常包含英文字形。但如果你对英文的显示效果有要求（比如需要特定的英文字体），可以分别设置：

Font chineseFont = new Font(baseFontChinese, 12); Font englishFont = new Font(baseFontEnglish, 12); Chunk chunk1 = new Chunk("中文部分", chineseFont); Chunk chunk2 = new Chunk("English Part", englishFont); Paragraph paragraph = new Paragraph(); paragraph.add(chunk1); paragraph.add(chunk2);

这种方式的灵活性最高，但代码量也最大。一般情况下，用一个中文字体就够了。

5.4 性能对比数据

我在实际项目中做过测试，往一个 10 页的 PDF 模板中每页写入 200 个中文字符，不同方案的对比如下：

可以看到，缓存BaseFont带来的性能提升非常明显。如果你的系统需要频繁生成 PDF，这个优化值得做。

6. 实际项目中的经验总结

6.1 我踩过的三个坑

第一个坑：用 FontFactory.getFont 加载中文字体。一开始我图省事，用FontFactory.getFont("SimHei", BaseFont.IDENTITY_H, BaseFont.EMBEDDED)来加载字体，结果在PdfStamper环境下死活显示不出中文。后来改成BaseFont.createFont直接指定字体文件路径，问题立刻解决。FontFactory依赖字体注册机制，在PdfStamper场景下不可靠。

第二个坑：字体文件放在项目根目录。本地测试没问题，部署到服务器上就报FontNotFoundException。原因是打包成 JAR 后，根目录的文件没有被包含进去。后来把字体文件放到src/main/resources/fonts/下，用 classpath 路径加载，问题解决。

第三个坑：忘记关闭 PdfStamper。PdfStamper如果不调用close()，输出文件是不完整的。而且close()会触发字体子集化的最终写入，如果提前关闭输出流，字体数据可能丢失。正确的顺序是：先stamper.close()，再reader.close()，最后os.close()。

6.2 一个实用的调试技巧

如果你不确定中文是否被正确写入，可以把生成的 PDF 用文本编辑器打开，搜索中文字符对应的 Unicode 码点。如果能在内容流里找到，说明写入成功，问题出在字体映射上；如果找不到，说明写入环节就有问题。

另一个技巧是用 iText 的PdfReader读取生成的 PDF，检查字体资源：

PdfReader reader = new PdfReader("output.pdf"); PdfDictionary pageDict = reader.getPageN(1); PdfDictionary resources = pageDict.getAsDict(PdfName.RESOURCES); PdfDictionary fonts = resources.getAsDict(PdfName.FONT); System.out.println("字体资源: " + fonts);

如果fonts为null或不包含你嵌入的字体，说明字体注册失败。

6.3 版本兼容性提醒

iText 5.5.10 是一个比较老的版本，虽然稳定但有一些已知的限制。如果你有条件升级，iText 7.x 在字体处理上做了大量改进，PdfStamper的替代品PdfDocument+Document组合对中文支持更好。但如果你维护的是老项目，锁死了 5.x 版本，本文的方案完全够用。

另外要注意，iText 5.x 的许可证是 AGPL，商业项目使用需要购买商业许可证。如果你只是内部使用或开源项目，AGPL 没问题；如果是商业闭源项目，建议确认一下授权情况。

6.4 最后分享一个小技巧

如果你需要写入的中文文本是动态的，比如从数据库读取的用户名、地址等，建议在写入前做一次字符过滤，把不支持的字符（比如某些特殊符号、emoji）替换掉。因为即使字体文件包含中文字形，也不一定包含所有特殊符号。我一般用这个正则来过滤：

String safeText = text.replaceAll("[^\\u4e00-\\u9fa5a-zA-Z0-9\\s.,;:!?，。；：！？]", "");

这个正则保留了常用中文、英文、数字和基本标点，过滤掉其他可能出问题的字符。虽然简单粗暴，但在实际项目中非常有效，能避免很多莫名其妙的显示问题。