OFD 在线预览全是乱码？我差点被“字体问题”带沟里了

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 预览乱码，可以直接对照：

1. 太相信"字体缺失"这个经验结论
2. 被 Mac 正常、Windows 异常的现象误导
3. 在 ofdrw 1.x 上浪费时间折腾字体映射
4. 忽略了库版本本身的历史问题

真正有效的一句话总结是：

ofdrw 1.x 遇到乱码，别折腾字体，直接升 2.x。

最后一句

很多线上问题，看起来是"环境问题""配置问题"，

但本质上只有一个原因：

你在用一个，早就该升级的版本。

希望这次踩坑记录，能帮你少走一点弯路。