OFD 在线预览全是乱码？我差点被“字体问题”带沟里了
一个看似简单的问题，最后却发现：你改的方向，从一开始就是错的。
前几天，现场同事反馈：
OFD 类型的发票文件在系统里在线预览时，几乎全是乱码。
第一眼看到截图，我脑子里立刻蹦出三个字：
缺字体。
第一坑：我太相信“经验判断”了
现场环境是 Windows Server，那问题就更合理了。
于是我直接从公司测试环境打包了一份 fonts 目录，让现场运维：
复制到 C:\Windows\Fonts
然后重启后端服务
这个操作我以前用过不止一次，成功率很高。
结果呢？
运维回复：还是不行。
到这一步，其实已经是个信号了 --
如果真是字体问题，不会一点改善都没有。
第二坑：跨平台表现，迷惑性极强
既然“玄学方案”不行，那就要原始 OFD 文件，自己跑一遍。
结果非常有意思：
- Mac 本地运行
👉 只有两三处乱码 - 公司 Windows Server
👉 和现场一模一样，大片乱码
这一下直接把我绕进去了。
同一份代码、同一份 OFD，
不同系统，结果完全不同。
如果你在这一步停下来，大概率会继续死磕“系统字体”。
我也差点。
第三坑：我把希望寄托在“字体映射”上
项目里用的是 ofdrw 做 OFD → PDF 转换。
我翻了一下 API，很快锁定几个“看起来就很对”的方法：
addAliasMapping（字体别名映射）loadExternalFont（加载外部字体）
于是开始各种组合尝试：
- 映射宋体
- 映射 Courier New
- 手动加载 ttf / ttc
结论只有一个：
完全没用。
这时候我才意识到一个问题：
也许问题根本不在“字体缺没缺”。
真正的原因：ofdrw 版本太老了
没办法，只能去翻 ofdrw 官方仓库和 issues。
结果在 issues 里看到一句话，直接点醒了我：
升级到 2.x
再一看项目：
- 当前使用：ofdrw 1.x
- 官方最新：2.x
老实说，我当时是有点犹豫的。
大版本升级，
谁心里不慌？
但继续往下翻，看到了作者的这段说明👇
（这段真的很关键）
看到这句话，我直接下定决心：
不折腾字体了，升级。
解决方案：只改了一行依赖
升级到当前最新版本 2.3.7：
implementation ('org.ofdrw:ofdrw-full:2.3.7') {
exclude group: 'org.apache.logging.log4j', module: 'log4j-slf4j-impl'
}
然后：
- 重启项目
- 上传 OFD
- 打开在线预览
结果：
✅ 乱码消失
✅ 无需额外字体
✅ Mac / Windows Server 表现一致
复盘一下，这次我踩了哪几个坑？
如果你以后也遇到 OFD 预览乱码，可以直接对照：
- 太相信“字体缺失”这个经验结论
- 被 Mac 正常、Windows 异常的现象误导
- 在 ofdrw 1.x 上浪费时间折腾字体映射
- 忽略了库版本本身的历史问题
真正有效的一句话总结是：
ofdrw 1.x 遇到乱码，别折腾字体，直接升 2.x。
最后一句
很多线上问题，看起来是“环境问题”“配置问题”，
但本质上只有一个原因：
你在用一个，早就该升级的版本。
希望这次踩坑记录，能帮你少走一点弯路。
