字体问题排查与解决记录日期2026-08-09环境Debian GNU/Linux 13 (trixie)OnlyOffice 9.4.0一、问题现象OnlyOffice 打开来自 Windows/WPS 的 Office 文档时出现排版错乱、文字空白、字体显示异常。二、根因分析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验证族名完整性fromfontTools.ttLibimportTTFont fTTFont(simfang.ttf)forrinf[name].names:ifr.nameIDin(1,16)andr.platformID3:print(r.nameID,r.toUnicode())三、解决步骤1. 安装 Windows 常用中文字体真实字体文件从 GitHub 仓库xoofee/chinese_fonts下载安装到系统字体目录sudocp*.ttf *.ttc /usr/share/fonts/truetype/windows-cn/sudofc-cache-f已安装字体字体文件名状态宋体 SimSunsimsun.ttc✅微软雅黑 Microsoft YaHei含粗体msyh.ttc / msyhbd.ttc✅黑体 SimHeisimhei.ttf✅楷体 KaiTisimkai.ttf✅仿宋 FangSongsimfang.ttf✅华文行楷 STXingkaiSTXINGKA.ttf✅注意下载需使用代理-x http://192.168.31.82:7890且必须用fontTools验证文件完整性损坏文件会导致空白。2. 安装微软英文字体从ttf-mscorefonts-installer的临时下载目录/tmp/ttf-mscorefonts-installer.*/中用cabextract手动解压*.exe中的字体forfin*.exe;docabextract-d/usr/share/fonts/truetype/msttcorefonts$fdone已装Arial、Courier New、Georgia、Impact、Tahoma、Comic Sans MS、Andale Mono。3. 清除 OnlyOffice 字体缓存OnlyOffice 缓存了字体列表AllFonts.js、font_selection.bin等不会每次启动都重新扫描系统字体。安装新字体后必须清除缓存并完全退出重启rm-rf~/.local/share/onlyoffice/desktopeditors/data/fonts/AllFonts.js*rm-rf~/.local/share/onlyoffice/desktopeditors/data/fonts/font_selection.binrm-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 字体。