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。
最後一句
很多線上問題，看起來是“環境問題”“配置問題”， 但本質上只有一個原因：
你在用一個，早就該升級的版本。
希望這次踩坑記錄，能幫你少走一點彎路。
