本文详解在 itext 7 中通过字体嵌入与编码匹配解决德语等 unicode 字符（如 ä、ö、ü、ß）无法正常显示的问题，涵盖字体选择、编码设置、源码保存格式及常见误区，确保硬编码字符串与用户输入均能正确渲染。
本文详解在 itext 7 中通过字体嵌入与编码匹配解决德语等 unicode 字符（如 ä、ö、ü、ß）无法正常显示的问题，涵盖字体选择、编码设置、源码保存格式及常见误区，确保硬编码字符串与用户输入均能正确渲染。
在使用 iText 7（kernel、layout、pdfa 等模块）生成 PDF 时，若文档中包含德语变音符号（如 ä、ö、ü、ß）或其它非 ASCII 字符，常出现空白、方块、问号或乱码——即使代码中明确指定 "UTF-8" 编码，问题仍持续存在。根本原因并非 iText 不支持 Unicode，而是字体编码模式、Java 源文件编码、PDF 字体嵌入策略三者未协同一致。
✅ 正确做法：使用 IDENTITY_H + 真实 Unicode 字体（推荐）
iText 7 中，处理多语言文本（尤其是含组合字符、扩展拉丁字母的文本）的唯一可靠方式是使用 IDENTITY_H 编码并嵌入支持 Unicode 的 TrueType 字体（如 Noto Sans、DejaVu Sans、FreeSans）。IDENTITY_H 启用 CID 字体机制，允许每个 Unicode 码点映射到字形，完全绕过传统单字节编码（如 UTF-8、CP1252、ISO-8859-1）的局限。
以下为可直接运行的完整示例：
import com.itextpdf.kernel.font.PdfFont;
import com.itextpdf.kernel.font.PdfFontFactory;
import com.itextpdf.kernel.font.PdfFontFactory;
import com.itextpdf.kernel.pdf.PdfDocument;
import com.itextpdf.kernel.pdf.PdfWriter;
import com.itextpdf.layout.Document;
import com.itextpdf.layout.element.Paragraph;
import java.io.IOException;
public class UnicodePdfExample {
public static void main(String[] args) throws IOException {
String outputPath = "german-unicode.pdf";
String fontPath = "font/FreeSans.ttf"; // 确保该路径下存在支持 Unicode 的 TTF 文件
PdfWriter writer = new PdfWriter(outputPath);
PdfDocument pdf = new PdfDocument(writer);
Document document = new Document(pdf);
// ✅ 关键：使用 IDENTITY_H 编码 + 嵌入字体（自动启用 CID）
PdfFont unicodeFont = PdfFontFactory.createFont(fontPath, "Identity-H", true);
// 硬编码字符串（源文件必须保存为 UTF-8！）
String text = "Hallo Welt! Grüße von München: äöü߀—…";
Paragraph p = new Paragraph(text).setFont(unicodeFont);
document.add(p);
document.close();
System.out.println("PDF generated with correct Unicode rendering.");
}
}? 关键参数说明：
- "Identity-H"：固定字符串，不可写作 "UTF-8" 或 "utf8"；这是 iText 7 中启用 Unicode 支持的专用标识；
- true：表示强制嵌入字体子集（推荐），确保 PDF 在任意设备上均可正确显示；
- 字体文件（如 FreeSans.ttf）必须真实包含 U+00E4（ä）、U+00F6（ö）等码位的字形（可使用 FontDrop 验证）。
⚠️ 常见错误与规避指南
| 错误做法 | 问题原因 | 正确替代 |
|---|---|---|
| PdfFontFactory.createFont(fontPath, "UTF-8") | "UTF-8" 是非法编码名，iText 7 会静默降级为 WinAnsiEncoding，导致 Unicode 丢失 | ✅ 改用 "Identity-H" |
| 使用 StandardFonts.HELVETICA + PdfEncodings.UTF8 | Helvetica Base 14 字体不包含 äöüß 等字符，编码设置无效 | ✅ 必须使用外部 TTF 并嵌入 |
| 源码文件保存为 GBK / ISO-8859-1 | Java 编译器按文件编码解析字符串字面量，若 .java 是 ISO-8859-1 但写入 ä，实际读为 0xE4（非 Unicode 码点） | ✅ IDE 中统一设为 UTF-8（IntelliJ/Android Studio → File → Settings → Editor → File Encodings） |
| 仅调用 document.setFont(font) 全局设置 | Paragraph 构造时若未显式绑定字体，可能回退到默认无 Unicode 支持的字体 | ✅ 每个文本元素显式 .setFont()（如示例中 new Paragraph(...).setFont(...)） |
? 补充建议
- 字体选择优先级：Noto Sans > DejaVu Sans > FreeSans > Arial Unicode MS（避免使用 Windows 默认字体，跨平台兼容性差）；
- 调试技巧：生成 PDF 后，用 Adobe Acrobat → 文件 → 属性 → 字体，确认字体是否“已嵌入”且编码为 CID-0；
- Web 应用注意：若文本来自 HTTP 请求，确保 request.setCharacterEncoding("UTF-8") 且响应头含 Content-Type: text/html; charset=UTF-8；
- iText 5 用户注意：本文方案仅适用于 iText 7.x；iText 5 需使用 BaseFont.IDENTITY_H + ColumnText 等不同 API。
遵循以上方案，无论是硬编码字符串 "Grüße"，还是从表单、数据库、API 获取的 UTF-8 字符串，均可在 PDF 中精准呈现，彻底告别乱码困扰。
