上周同事递过来一个导出PDF的工单：JasperReport 6.x 项目在 JasperSoft Studio 里预览好好的，一旦跑在 Spring Boot 服务里，导出的 PDF 所有中文都变成空心方框；控制台里不断刷出Unpatched iText found, cannot use glyph rendering这一行。第一眼看到这条提示，任何人都会觉得是 iText 没打补丁的锅，可我把 iText 版本翻来覆去比对、折腾了大半天，最后才意识到问题从来不在 iText 身上。这篇就把完整的排查思路和可直接落地的配置写出来，给正在被同样问题折磨的同学做个参照，顺便理清这条提示的真实含义。
1. 这行提示的真实身份：不是报错，更像一个"环境体检报告"
先说结论：Unpatched iText found, cannot use glyph rendering是 JasperReports 6.x 在初始化 PDF 导出环境时输出的一条提示，不是异常堆栈，也不代表这次导出一定失败。它之所以让你紧张，是因为它的出现时机恰好和"汉字全部变方框"重合，两者很容易被误认为因果关系。
1.1 为什么从 6.11 之后这行字见得多了
根据我接触过的项目来看，这条提示在 6.x 早期版本里很少出现，从 6.11 开始变频繁。原因是 JasperReports 更新了 PDF 渲染路径，加入了一套基于字形（glyph）的渲染机制，想用它来做更精确的文本排版和字体回退。这套机制要求底层 iText 必须是"打过补丁的版本"。
这里说的"补丁"，指的是 JasperReports 官方维护的 iText 分支。它和开源原生 iText 的关系，可以理解成同一个库的两个构建产物：功能主体一样，但补丁版额外带了 JasperReports 需要的字形处理接口。项目里最常见的 Maven 坐标是com.lowagie:itext:2.1.7.js6，这个带js6后缀的版本就是配套补丁版。如果你的 classpath 里加载的是没有js6后缀的原版2.1.7，JasperReports 就能检测到"你用的 iText 不是我要的那个定制版"，于是打出这行提示。
比较坑的是，这个提示不一定走 logback/log4j 日志框架。它经常直接打在标准输出或者应用控制台上，导致你在application.yml里把日志级别调到 DEBUG 也搜不到它，只有去容器控制台看原始输出才能看到。这也解释了为什么很多人排查时总觉得日志"缺了一块"。
1.2 一个容易被忽略的依赖污染场景
我在排查那个工单时，第一轮就把mvn dependency:tree拉出来看了，结果发现项目里同时存在两条com.lowagie:itext依赖：
- 一条来自
net.sf.jasperreports:jasperreports，版本是2.1.7.js6； - 另一条来自某个操作 Word 文档的辅助库，传到项目里的是原版
2.1.7。
两条依赖共存时，实际加载哪个类版本完全取决于 classpath 顺序，而这个顺序谁都没法保证。一旦原版 iText 的类先被加载，JasperReports 检测到的就是"Unpatched iText"，字形渲染直接被禁用。
所以排查这个提示的第一步，不是去下载补丁，而是先确认自己的依赖树里有没有混入原版 iText。常见做法是给 JasperReports 的依赖加上排除项，再把其他库传递进来的旧版 iText 排除掉，只保留js6版本。这个动作本身花不了十分钟，但能把大量后续问题消灭在源头。
2. 中文变方框的完整因果链：从fontName到PDF字形映射
把 iText 版本统一之后，我原以为问题就解决了，结果导出 PDF 里的中文依然是方框。这时才意识到，提示归提示，真正导致汉字不显示的是另一条链路：JRXML 里的fontName到 PDF 字形映射。
2.1 JasperReports 渲染中文字体的完整过程
理解这个问题，需要先知道一段文本在导出 PDF 时经历了什么。JasperReports 拿到 JRXML 模板后，会读取文本元素上的fontName属性，把它解析成一个"字体族"对象；导出 PDF 时，再通过字体族找到具体的字体文件位置，加载字体文件并把字符映射成字形（glyph），最后嵌入 PDF。整个过程可以简化成：
- JRXML 里写了
fontName="宋体"； - 报表引擎在本项目已注册的字体族里查找叫"宋体"的字体；
- 找不到就直接回退到默认字体，而默认字体通常是 DejaVu Sans；
- DejaVu Sans 不包含中文字形，Unicode 到字形的映射链在这里断掉；
- PDF 阅读器为了显示一个"存在但无法映射"的字符，只能画一个方框。
关键点在第三步：JasperReports 不会主动去扫描操作系统里装了哪些字体。很多人以为服务器上装了宋体、黑体，JRXML 里写fontName="宋体"就能生效，这是个非常普遍的误解。它在开发机上偶尔能生效，是因为 JVM 的 AWT 字体查找机制兜了底，但在没有桌面环境的 Linux 容器里，这个兜底往往是不存在的，于是静默回退到 DejaVu。
2.2 为什么 iTextAsian 方案在新项目里越来越不吃香
网上提到中文不显示，十有八九会建议你引入itext-asian依赖，然后用内置字体STSong-Light+UniGB-UCS2-H编码。这个方案在 JasperReports 5.x 时代确实很流行，因为那时候项目普遍直接操作 iText API，用内置 CID 字体最省事。
但放在 JasperReports 6.x + Spring Boot 的场景里，我个人的经验是这个方案优先级要往后放。原因有两个：一是itext-asian的 jar 需要手动安装到本地 Maven 仓库，在公司内部私服管理严格的团队里会多一道审批流程；二是它走的是 PDF 标准字体的 CID 引用路径，字体并不真正嵌入 PDF 文件，在某些 PDF 阅读器和打印场景下表现不稳定，而且使用限制也比嵌入式字体多。
相比之下，自定义字体扩展（Font Extensions）才是 JasperReports 官方推荐的长期方案。它把中文字体文件直接打包进应用，通过fonts.xml声明字体族，JRXML 里用自定义的fontName引用，字体跟随 PDF 一起嵌入。这套机制从 5.x 到 6.x 一直存在，配置方式几乎没变过，稳定性和可移植性都更好。
2.3 一个值得先做的快速自测
排查阶段，我建议你先手动确认一下"汉字不显示"到底是哪一种表现：
| 表现 | 说明 | 第一排查方向 |
|---|---|---|
| 空白字符，占位还在 | 字形映射失败 | 字体族注册、字体文件是否包含中文 |
| 方框或豆腐块 | 字形存在但 PDF 渲染异常 | 字体嵌入、pdfEncoding |
| 问号或乱码 | 编码转换失败 | text 元素编码、字体文件损坏 |
| 导出直接报异常 | 字体文件加载失败 | 路径、权限、字体文件格式 |
我当时那个项目就属于"方框"这一类。看到这个表现后，基本可以锁定问题在字体文件本身或字体注册配置上，和 iText 补丁没有直接关系。
3. Spring Boot工程里的中文字体扩展落地配置（可直接照抄）
下面这套配置，我后来在好几个 Spring Boot + JasperReport 6.x 项目里重复使用过，每一步都是踩过坑之后稳定下来的版本。如果你也是被这个问题卡住，可以直接照着搭。
3.1 准备字体文件时的一个选择：OTF还是TTF
中文字体我优先推荐思源黑体（Source Han Sans）或者文泉驿正黑。思源黑体是开源字体，覆盖的汉字全，字形规范，导出效果接近常见的"微软雅黑"，而且它的授权协议允许嵌入 PDF 和子集化，没有版权风险。
选文件格式时有个小坑：思源黑体官方发布的是 OTF，JasperReports 6.x 在多数情况下能识别 OTF，但 OTF 里如果包含的是 CFF 轮廓，部分 iText 版本在嵌入阶段会报奇怪错误。稳妥的做法是选同系列里打包好的 TTF 版本，或者下载后用字体工具转换成 TTF。我自己习惯直接找SourceHanSansSC-Regular.ttf这类 TTF 文件，能少很多无谓的兼容性折腾。
字体文件数量上，不要把全部字重都塞进去。对绝大多数报表来说，准备 Regular 和 Bold 两个文件就足够应付了。斜体在中文排版里基本用不到，后面会细说缺失字重会带来什么问题。
3.2 工程目录、扩展注册文件与fonts.xml配置
目录结构建议这么放：
src/main/resources/ ├── jasperreports_extension.properties └── fonts/ ├── fonts.xml ├── SourceHanSansSC-Regular.ttf └── SourceHanSansSC-Bold.ttf这个结构里有三个关键点。
第一，jasperreports_extension.properties必须放在 classpath 根目录，也就是src/main/resources下。JasperReports 启动时会在 classpath 里自动寻找这个文件，通过它来发现你注册的扩展。
第二，fonts.xml放在fonts/目录下。但注意，fonts.xml里的字体文件路径基准也是 classpath 根目录，不是src/main/resources。也就是说，路径写fonts/SourceHanSansSC-Regular.ttf，而不是src/main/resources/fonts/xxx.ttf。
fonts.xml内容如下：
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE fontFamilies SYSTEM "http://jasperreports.sourceforge.net/dtd/fontFamily.dtd"> <fontFamilies> <fontFamily name="SourceHanSans"> <normal>fonts/SourceHanSansSC-Regular.ttf</normal> <bold>fonts/SourceHanSansSC-Bold.ttf</bold> <italic>fonts/SourceHanSansSC-Regular.ttf</italic> <boldItalic>fonts/SourceHanSansSC-Bold.ttf</boldItalic> <pdfEncoding>Identity-H</pdfEncoding> <pdfEmbedded>true</pdfEmbedded> <exportFonts> <export key="net.sf.jasperreports.html">SourceHanSans</export> <export key="net.sf.jasperreports.xls">SourceHanSans</export> <export key="net.sf.jasperreports.csv">SourceHanSans</export> <export key="net.sf.jasperreports.rtf">SourceHanSans</export> </exportFonts> </fontFamily> </fontFamilies>jasperreports_extension.properties内容：
net.sf.jasperreports.extension.registry.factory.fonts=net.sf.jasperreports.engine.fonts.SimpleFontExtensionsRegistryFactory net.sf.jasperreports.extension.fonts.font.families=fonts/fonts.xml注意编码是 UTF-8。数据库导入、Excel 模板这类东西出乱码的案例太多，配置文件这一环也别偷懒。
第三，pdfEncoding设置为Identity-H，pdfEmbedded必须为true。Identity-H对 TTF 字体是能正常工作的一种编码方式，它按 Unicode 直接映射字形，适合中英文混排。如果你用的是 CID 标准字体方案，那里才需要UniGB-UCS2-H，但自定义字体扩展用Identity-H是最稳的。
3.3 JRXML里的fontName怎么改：用全局样式最省事
字体扩展配置好后，JRXML 里每个文本元素的fontName都要改成SourceHanSans，也就是fonts.xml里声明的fontFamily name。注意这个名字必须完全一致，大小写也不能错。
如果模板还没生成，在设计阶段就把字体统一设好最省事。JasperSoft Studio 里操作路径是：选中文本元素，打开属性面板，Font Name 下拉框里选择 SourceHanSans。
如果模板已经有很多页了，一个个去改文本元素太痛苦。更好的办法是先在 Studio 里定义一个全局样式（Style），把它应用到所有文本元素；后续想换字体，只改一处即可。项目里如果是一批历史模板，还可以用文本替换工具直接批量处理 JRXML 源文件，把<font fontName="宋体"/>替换成<font fontName="SourceHanSans"/>，前提是团队里模板的版本控制做得比较规范。
3.4 pom依赖版本统一与itext污染排查
Maven 依赖里，JasperReports 6.x 自身的依赖已经包含补丁版 iText，所以正常情况下你不需要显式引入。但如果项目里有别的库把 iText 的旧版本传递进来了，就要手动干预。给 JasperReports 的依赖加一个完整段落，确保它用的 iText 是带js6后缀的：
<dependency> <groupId>net.sf.jasperreports</groupId> <artifactId>jasperreports</artifactId> <version>6.20.5</version> </dependency>然后跑一遍mvn dependency:tree | grep itext，看看有没有出现两条com.lowagie:itext。如果有，用<exclusions>把不需要的那条排除掉。这一步做完，刚才那个Unpatched iText提示通常就会消失，因为补丁版 iText 重新占据了 classpath 主导位置。
配置完成后重启服务，重新导出。验证方法很简单：拿到 PDF 文件，打开"文档属性 → 字体"标签页，如果里面列出了 SourceHanSans，而且"嵌入"状态显示"是"，说明字体已经成功嵌入，这版配置就算跑通了。
4. Linux服务器上翻车的两个隐藏杀手：系统字体与临时目录缓存
本地 Windows 环境把配置改完，导出 PDF 一切正常，我一度以为事情结束了。结果部署到 Linux 测试服务器，中文又是方框，而且这次连Unpatched iText提示都没了，排查难度反而更高。在 Linux 环境下，有两个隐藏杀手值得专门讲一讲。
4.1 Linux系统本身缺中文字体，但不是唯一原因
第一个杀手是系统缺少中文字体。理论上，自定义字体扩展机制下，JasperReports 不需要依赖操作系统字体，因为 TTF 文件是打包在应用里的。但问题在于项目里往往不止 JasperReports 一个组件在渲染文本。比如某些图表库、二维码组件，或者打印预览的 AWT 绘制环节，仍然会通过java.awt.Font去查找系统字体。一旦查不到中文字体，这些环节就会默默降级或者输出乱码，让人误以为是报表引擎的问题。
上服务器后先跑这条命令确认：
fc-list :lang=zh如果输出为空，说明系统里一个中文字体都没有。解决办法是安装系统级中文字体包，或者直接把项目里的 TTF 文件复制到系统字体目录：
mkdir -p /usr/share/fonts/truetype/sourcehansans cp SourceHanSansSC-Regular.ttf SourceHanSansSC-Bold.ttf /usr/share/fonts/truetype/sourcehansans/ fc-cache -f -v容器镜像里也一样，Dockerfile 中加上安装字体的步骤。别以为应用自己带了字体文件就算完，AWT 那条链路不在你控制范围内。
4.2 改了配置不生效？先怀疑临时目录缓存
第二个杀手是临时目录里的缓存。JasperReports 在运行过程中会在${java.io.tmpdir}下生成临时文件，有些版本对字体扩展元数据做了缓存处理。表现就是：你明明改了fonts.xml，甚至字体文件都换了一个，重启应用后导出的 PDF 还是老样子，让人一度以为改错了地方。
我当时的处理方式简单粗暴但也有效：先把应用停掉，清一下临时目录：
rm -rf /tmp/jasperreports然后重启应用。如果项目跑在 Docker 容器里，容器重建时$TMPDIR是干净的，一般不用管；但如果你复用了同一个容器不重启，只是改了 jar 包里的配置，这个缓存就可能一直留着。为了验证是不是缓存作祟，可以在重启的时候加一句临时日志输出，看字体扩展注册路径到底指向哪里的文件。
4.3 一个容易被误导的排查方向：日志去哪了
还有一点要提醒：前面说过Unpatched iText found这行可能直接打到标准输出，不经过日志框架。在 Linux 服务器上排查时，如果只看app.log，很可能什么异常都看不到，但奇怪的是 PDF 里中文照样是方框。这种情况不要急着怀疑字体配置，先把服务停掉，用nohup或直接前台启动方式跑一次，观察控制台原始输出，往往能发现多出的信息。
5. 进阶细节：字体子集化、粗体缺失与"让警告消失"的执念
核心问题解决之后，还有几个和"中文导出"相关的进阶细节。这些细节不影响第一版跑通，但在生产环境上线前最好都过一遍。
5.1 嵌入式字体导致PDF体积暴涨，子集化怎么处理
中文字体文件体积大，嵌入 PDF 后文件体积也随之暴涨。一个完整思源黑体 Regular 就有 8MB 以上，如果模板用到大量中文文本，导出 PDF 可能从几百 KB 变成十几 MB，接口响应变慢，存储成本也跟着涨。
处理办法是字体子集化：只保留模板实际会用到的那部分汉字和符号，把字体文件裁剪成几百 KB 的小文件，再喂给 JasperReports 字体扩展。我常用的是开源工具fontTools的pyftsubset命令：
pyftsubset SourceHanSansSC-Regular.otf \ --text-file=chars.txt \ --output-file=SourceHanSansSC-Subset.ttf其中chars.txt是模板里出现的所有字符集合。最实用的做法不是手工录入 3500 个常用字，而是把历史导出数据里出现过的人名、地名、备注字段都收集起来，连同常用汉字一起放进chars.txt，这样既控制体积，又能覆盖实际业务场景。子集化之后的字体文件可以继续沿用fonts.xml里的配置，只是把<normal>路径指向裁剪后的文件即可。
5.2 粗体与斜体缺失：一个低报错率的隐蔽坑
如果fonts.xml里只注册了<normal>，没有注册<bold>，JasperReports 在遇到设置了bold="true"的文本元素时，行为很微妙：它不一定报错，而是在日志里留一句字体族找不到对应变体的提示，然后用普通字重渲染。最终导出的 PDF 里，本该加粗的文字全部是常规字重，如果没人仔细核对，这个坑能潜伏很久。
所以配置字体族时，尽量把<bold>也配好，至少让boldItalic指向和<bold>同样的字体文件。斜体如果是中文，一般不会真正倾斜，直接映射回normal也没问题，但至少别让这个变体成为空引用。
5.3 到底要不要为了消除提示而换iText版本
有人执着于让Unpatched iText found从日志里彻底消失，甚至考虑把 iText 换成商业授权版本。我的观点是：不要为了一条提示做出超出实际需要的改动。
这条提示真正影响的，是"基于字形的高级渲染"这个能力，而不是基础的中文字体嵌入。如果你当前的场景是常规中文报表，字体已经正确注册嵌入，PDF 在主流阅读器里都能正常显示，那么这条提示更像一个环境兼容性信息，对业务没有任何影响。反过来，如果你只是把 iText 换成商业版，却没有把字体扩展配置对，中文照样不显示，钱花了问题还在。
真正需要关注这条提示的场景，是遇到复杂的文本排版需求，比如特殊组合字符、复杂脚本文本渲染，或者用户反馈某些字符在某个 PDF 阅读器里渲染不对。这种时候才值得去检查 iText 补丁版本是否确实缺失。
5.4 模板里styled标记导致的加粗失效
最后一个冷门问题：JRXML 里如果文本元素设置了markup="styled"，并且内容里用了<b>标签，那么渲染时它会强制查找字体族的 bold 变体。如果fonts.xml里<bold>缺失或指向错误，报表引擎会按照"找不到变体"的逻辑处理，结果就是在线预览和导出 PDF 里加粗效果不一致。排查时如果遇到 "预览里是加粗的，导出的 PDF 却没有加粗" 这种诡异情况，先看markup属性，再看字体族的变体配置，别去动文本内容本身。
经历过这次排查之后，我反而觉得"Unpatched iText found"是一个信号，而不是故障本身。它提醒你环境里的 iText 版本可能不是你预期的版本，然后再顺着这条线去查字体加载链路。现在我的排查顺序已经固定下来了：先看依赖树里有没有重复的 iText，再看 PDF 输出的字体列表确定字体是否嵌入，最后才去翻控制台的原始输出。顺序对了，大部分中文不显示的问题都能在半小时内定位，而不是像我第一次那样在无关的问题上耗掉一整天。
