OnlyOffice 打开来自 Windows/WPS 的 Office 文档时，出现排版错乱、文字空白、字体显示异常。

字体问题排查与解决记录

日期：2026-08-09

环境：Debian GNU/Linux 13 (trixie)，OnlyOffice 9.4.0

一、问题现象

二、根因分析

1. 缺少 Windows 商业字体

系统预装的是 Noto CJK 系列开源字体，不包含 Windows 常用商业字体。文档中指定的字体（宋体、微软雅黑、黑体、楷体、仿宋、华文行楷等）在系统中不存在时，OnlyOffice 会回退到替代字体，导致排版错乱。

2. OnlyOffice 不认 fontconfig 的字体名映射

通过修改 ~/.config/fontconfig/fonts.conf 把"宋体"映射到 Noto Serif CJK 等做法，对 LibreOffice 有效，但对 OnlyOffice 无效。OnlyOffice 只认真实存在的字体文件，不认名字替换。其字体列表中没有"宋体"等虚拟字体名，文档里用到时依旧被替换。

3. 部分下载的字体文件损坏

从 GitHub 下载的字体文件，如果下载不完整（代理中断），会导致字体文件内部表数据损坏、族名错乱（如 simfang.ttf 族名变成小写文件名 simfang 而不是 仿宋/FangSong）。OnlyOffice 匹配不到正确族名，渲染成空白。需用 fontTools 验证族名完整性：

python 复制代码

from fontTools.ttLib import TTFont
f = TTFont('simfang.ttf')
for r in f['name'].names:
    if r.nameID in (1, 16) and r.platformID == 3:
        print(r.nameID, r.toUnicode())

三、解决步骤

1. 安装 Windows 常用中文字体（真实字体文件）

从 GitHub 仓库 xoofee/chinese_fonts 下载，安装到系统字体目录：

bash 复制代码

sudo cp *.ttf *.ttc /usr/share/fonts/truetype/windows-cn/
sudo fc-cache -f

已安装字体：

字体	文件名	状态
宋体 SimSun	simsun.ttc	✅
微软雅黑 Microsoft YaHei（含粗体）	msyh.ttc / msyhbd.ttc	✅
黑体 SimHei	simhei.ttf	✅
楷体 KaiTi	simkai.ttf	✅
仿宋 FangSong	simfang.ttf	✅
华文行楷 STXingkai	STXINGKA.ttf	✅

注意：下载需使用代理 -x http://192.168.31.82:7890，且必须用 fontTools 验证文件完整性，损坏文件会导致空白。

2. 安装微软英文字体

从 ttf-mscorefonts-installer 的临时下载目录（/tmp/ttf-mscorefonts-installer.*/）中，用 cabextract 手动解压 *.exe 中的字体：

bash 复制代码

for f in *.exe; do
  cabextract -d /usr/share/fonts/truetype/msttcorefonts "$f"
done

已装：Arial、Courier New、Georgia、Impact、Tahoma、Comic Sans MS、Andale Mono。

3. 清除 OnlyOffice 字体缓存

OnlyOffice 缓存了字体列表（AllFonts.js、font_selection.bin 等），不会每次启动都重新扫描系统字体。安装新字体后必须清除缓存并完全退出重启：

bash 复制代码

rm -rf ~/.local/share/onlyoffice/desktopeditors/data/fonts/AllFonts.js*
rm -rf ~/.local/share/onlyoffice/desktopeditors/data/fonts/font_selection.bin
rm -rf ~/.local/share/onlyoffice/desktopeditors/data/fonts/fonts_thumbnail*

4. 移除 fontconfig 名字映射

真实字体装好后，应删除之前为映射 Windows 字体名到 Noto 而写的 ~/.config/fontconfig/fonts.conf，否则它会继续把宋体/仿宋等强制替换成 Noto，导致 OnlyOffice 排版依旧不对。

四、经验总结

OnlyOffice 只认真实字体文件，不做名字映射------要装真实字体，而不是配置替换。
下载字体必须校验文件完整性，损坏文件会静默产生空白/错乱。
安装新字体后必须清除 OnlyOffice 缓存并完全重启。
不要保留多余的 fontconfig 名字映射，会覆盖真实字体。
判断依据：fc-match "宋体" 应返回 simsun.ttc: "宋体" 而非 Noto 字体。