我先把话放在这儿：如果你在Linux服务器上用Docker部署OnlyOffice，打开中文docx文档看到满屏方块、转PDF中文变“豆腐块”，十有八九不是软件坏了，而是容器里压根没有中文字体。这个坑几乎每个部署OnlyOffice的人都会踩一遍，我自己的生产环境也翻过车，那次排查了整整一个下午，最后才发现是字体问题。这篇文章就围绕“Linux环境下给OnlyOffice容器补中文字体”这件事，把原理、方案、实操、坑位一次讲透，分享给正在被中文乱码折磨的运维和部署同学。
1. 乱码背后的根源：镜像里根本没有中文字体
1.1 一次“豆腐块”事故的完整现场
先还原一下场景。我当时的部署方式是标准的docker pull onlyoffice/documentserver，一条docker run把服务拉起来，端口映射好，NextCloud那边也配置好了在线编辑。结果第一个正式文档发过来，打开后标题能显示，正文里的中文全变成一个个小方框，英文和数字完全正常。更奇怪的是，同一个docx在本地WPS打开完全没问题，上传到OnlyOffice就乱。
很多人第一反应是编码问题，去改数据库字符集、改JWT配置、改Nginx配置，甚至有人怀疑是NextCloud传输过程破坏了文件。实际上把服务端生成的PDF下载下来看，里面中文依然是方块，这才想起来去查容器里到底有没有中文字体。一查果然，fc-list :lang=zh输出几乎是空的，系统里连一个能渲染中文的字体都没有。
这类问题的影响范围比想象中大得多。不只是在线预览，还包括文档转换为PDF、PPT放映时字体度量计算、表格列宽自动调整，甚至协同编辑时不同用户看到的排版差异。只要服务端渲染环节用到中文字，就全部受影响。换句话说，OnlyOffice的中文能力，完全建立在容器字库是否完整之上。
1.2 OnlyOffice为什么依赖系统字体
OnlyOffice DocumentServer的转换和预览内核叫x2t，它处理文档时并不会像桌面Office那样把字体打包在软件里，而是直接调用Linux系统底层的字体渲染管线。Linux下负责这个工作的是一套叫fontconfig的字体管理系统，应用程序通过它查询可用字体、匹配字体别名、获取字体文件路径。
所以问题链条是这样的：docx里写着“微软雅黑”或“宋体”→ OnlyOffice转换内核向fontconfig要这个字体 → fontconfig在系统字体目录里翻了个遍，没有 → 字体匹配失败，回退到默认字体 → 默认字体又不支持中文 → 渲染结果变成方块。整个过程中OnlyOffice本身没有任何错误提示，它只是安静地告诉你“这个字体我找不到，随便拿个凑合吧”，结果就是你看不懂的文字。
理解这个机制之后，解决方案就很清晰了：往容器的字体目录里放中文字体，让fontconfig能查到、能匹配上。只要字体文件进去了，渲染链路就通了。
1.3 宿主机的字体为什么帮不上忙
这里有个很常见的误区。很多人在宿主机上明明装了中文字体，fc-list查宿主机也有一大堆Noto CJK，但容器里的OnlyOffice还是乱码。原因很简单，Docker容器是独立文件系统，容器内的进程看不到宿主机的/usr/share/fonts目录，除非启动容器时显式用-v把目录挂载进去。
这也解释了另一个现象：为什么在Docker Desktop这类带共享机制的桌面环境里问题不明显，而在纯命令行服务器环境里几乎必现。桌面Docker通常会默认共享部分本机目录，而云服务器、内网机房的Linux环境一般不会这么做。只要理解容器隔离这一点，你就不会再把时间浪费在折腾宿主机字体上了。
2. 三个方案，从“紧急止血”到“长期合规”
2.1 方案横评
给容器补字体，我实际常用三种方式，各有适用场景。用一张表格先做个对比：
| 方案 | 适用场景 | 容器重建后是否保留 | 操作便捷度 | 是否适合生产 |
|---|---|---|---|---|
| docker cp 快速复制 | 容器已在运行，只想马上看效果 | 不保留，重建即失效 | 最简单 | 不适合 |
| 启动时挂载字体目录 | 长期运行，可以接受重启容器 | 保留，重启不丢失 | 简单 | 推荐 |
| 基于Dockerfile构建定制镜像 | 团队交付、CI/CD发布 | 保留，镜像层面固化 | 需要构建流程 | 最推荐 |
这三个方案并不是互相排斥的。我的习惯是：临时排障用docker cp，快速解决问题；顺手就补一套挂载目录方案；最终稳定下来后，把字体和fontconfig配置固化到自定义镜像里，这样以后无论部署到哪台机器，拉镜像就能用。
2.2 方案一：docker cp 快速修复
这个方案适合容器已经跑着、不想动服务的情况。步骤很简单，先把宿主机上的中文字体目录准备好，然后复制进容器，刷新字体缓存：
docker cp /opt/onlyoffice/chinese-fonts onlyoffice-docserver:/usr/local/share/fonts/chinese docker exec onlyoffice-docserver fc-cache -fv docker restart onlyoffice-docserver这里我故意把字体放在/usr/local/share/fonts/chinese而不是直接放/usr/share/fonts，因为fontconfig默认会递归扫描/usr/local/share/fonts，放在这里不用改配置文件，也不会覆盖镜像原有的字体目录结构。
这个方案的最大问题是不可持久化。容器一旦被删除重建，字体就丢了，你得重新执行一遍。如果你只是本地测试验证一下，那完全没问题；但如果一个部署方案长期依赖docker cp，那就是给自己埋雷。
2.3 方案二：启动时挂载字体目录
生产环境我推荐用挂载方式，把宿主机的一个目录映射到容器的字体目录里。这样字体文件只维护一份，宿主机上改完字体文件后重启容器即可，不涉及进入容器操作，也不怕容器重建。
启动命令如下：
docker run -itd \ --name onlyoffice-docserver \ -p 8080:80 \ -v /opt/onlyoffice/chinese-fonts:/usr/local/share/fonts/chinese:ro \ onlyoffice/documentserver:latest挂载时加上:ro是防止容器内误写宿主机字体文件，也提醒自己这个目录是只读的。用这个方案后，我更新字体只需要替换宿主机的/opt/onlyoffice/chinese-fonts目录里的文件，然后docker restart onlyoffice-docserver，字体就更新了，不需要进入容器，非常省事。
2.4 方案三：构建OnlyOffice定制镜像
如果公司内部有镜像仓库，或者你用Docker Compose、Kubernetes做编排，那更推荐构建一个带中文字体的定制镜像，把字体直接固化进镜像里。
FROM onlyoffice/documentserver:latest COPY chinese-fonts/ /usr/local/share/fonts/chinese/ RUN fc-cache -fv构建命令：
docker build -t myregistry/onlyoffice-docserver:zh-latest .构建好之后推到镜像仓库，部署的时候拉取这个定制镜像即可。以后无论扩容还是灾备恢复，镜像里自带中文字体，不存在“忘记拷字体”这种事。不过这个方案有个小缺点：OnlyOffice官方镜像更新后，你得重新构建一次自己的定制镜像。所以建议写一个自动化构建脚本，官方镜像一发新版，触发你的构建流水线自动把字体打进去。
3. 字体不是“有就行”：选字体的门道
3.1 别再copy微软雅黑了，先聊版权
很多人想到中文字体，第一反应就是把Windows系统里的msyh.ttc（微软雅黑）或simsun.ttc（宋体）拷贝到Linux服务器上。这个做法在企业内部自用场景下风险相对可控，但严格来说，微软中文字体是有版权限制的，不能随意分发、嵌入或用于商业服务。如果你把包含微软雅黑的镜像推到公共仓库，或者交付给外部客户，就可能存在法律风险。
更稳妥的选择是用开源中文字体。我长期用的是思源黑体（Source Han Sans / Noto Sans CJK）和思源宋体（Noto Serif CJK），这两套字体由Adobe和Google主导开发，采用SIL开源字体许可证，可以免费商用、自由分发。文泉驿系列也是老牌开源字体，适合轻量场景，但字重和字形完整度不如思源。如果你处理的文档里既有中文又有日文韩文，思源黑体的CJK全包版本还能一并解决多语言问题，后面扩展也不用再折腾。
3.2 字体该放哪个目录、权限怎么给
Linux字体目录的选择有点讲究。/usr/share/fonts是系统级字体目录，/usr/local/share/fonts是本地附加字体目录，两者的区别在于：前者是系统包管理器安装字体时的默认位置，后者是管理员手动添加字体的标准位置。对于Docker挂载场景，我更推荐用/usr/local/share/fonts下的子目录，这样既不会跟镜像自带字体混在一起，也符合fontconfig的目录约定。
字体文件权限是容易被忽略的坑。OnlyOffice容器内的进程通常以普通用户身份运行，如果字体文件的权限是600，进程没有读取权限，字体装了也等于没装。我的习惯是统一设置成644，目录设置成755：
chmod 644 /opt/onlyoffice/chinese-fonts/* chmod 755 /opt/onlyoffice/chinese-fonts另外注意，字体文件必须是Linux能识别的格式，.ttf、.ttc、.otf都没问题，但Windows下的.fon这类点阵字体在Linux下基本不可用，不用浪费时间。
3.3 一劳永逸的字体别名配置
光把字体装进容器还不够，这里还有第二个坑：很多中文文档里写死的字体名是“宋体”“微软雅黑”“SimSun”这类名称，而Linux里安装的是“Noto Sans CJK SC”，名字对不上，fontconfig照样匹配不到。
解决办法是给fontconfig配置字体别名，把中文字体家族映射到思源字体上。我写了一个别名配置文件，实测效果很好：
<?xml version="1.0"?> <!DOCTYPE fontconfig SYSTEM "fonts.dtd"> <fontconfig> <match target="pattern"> <test qual="any" name="family"> <string>SimSun</string> <string>宋体</string> <string>Microsoft YaHei</string> <string>微软雅黑</string> </test> <edit name="family" mode="assign" binding="strong"> <string>Noto Sans CJK SC</string> </edit> </match> </fontconfig>这个配置的意思是：当文档请求SimSun、宋体、微软雅黑这些字体时，fontconfig直接把请求替换成Noto Sans CJK SC。如果不加这个配置，即使系统里字体很多，遇到指定了宋体或雅黑的旧文档，渲染出来还是可能变样。
使用挂载方案时，这个配置文件也要挂进容器的/etc/fonts/conf.d/目录。注意一定要挂载成单文件，不要挂载整个conf.d目录，否则会覆盖镜像自带的字体配置。
4. 实操全程：以挂载方案为例，从中文字体到正常渲染
4.1 第一步：准备宿主机字体目录
我先在宿主机上创建一个专门的字体目录，用来存放OnlyOffice容器需要的中文字体：
mkdir -p /opt/onlyoffice/chinese-fonts cd /opt/onlyoffice/chinese-fonts如果你的宿主机是Debian/Ubuntu，可以直接用包管理器安装思源黑体，速度最快，也不用去GitHub下载：
apt-get update apt-get install -y fonts-noto-cjk安装后把字体文件复制到我们的专用目录里：
find /usr/share/fonts -name "*NotoSansCJK*" -o -name "*NotoSerifCJK*" | head -20 cp $(find /usr/share/fonts -name "*NotoSansCJK*" -o -name "*NotoSerifCJK*") /opt/onlyoffice/chinese-fonts/如果宿主机是CentOS/RHEL，可以用yum install google-noto-sans-cjk-fonts。要是包管理器里找不到，就去GitHub的Noto CJK Releases页面下载OTF文件，记得选NotoSansCJKsc-Regular.otf和NotoSansCJKsc-Bold.otf两个就够了，全家族下载下来有几百MB，没必要。
4.2 第二步：配置字体别名文件
在宿主机上创建fontconfig配置目录和文件：
mkdir -p /opt/onlyoffice/fontconf vim /opt/onlyoffice/fontconf/60-zh-alias.conf把上面3.3节那个XML配置粘进去保存。这个文件等会要挂载到容器里，所以注意文件权限也要644，确保容器内进程可读。
4.3 第三步：启动容器并挂载字体与配置
如果你还没有启动容器，直接用下面的命令一步到位：
docker run -itd \ --name onlyoffice-docserver \ -p 8080:80 \ -v /opt/onlyoffice/chinese-fonts:/usr/local/share/fonts/chinese:ro \ -v /opt/onlyoffice/fontconf/60-zh-alias.conf:/etc/fonts/conf.d/60-zh-alias.conf:ro \ onlyoffice/documentserver:latest如果容器已经在运行了，那就停掉旧容器，重新用挂载参数启动：
docker stop onlyoffice-docserver docker rm onlyoffice-docserver # 然后执行上面的docker run命令这里要提醒一句：OnlyOffice容器内部自己管理着PostgreSQL数据库和密钥文件，直接删容器重建会导致已上传的文档链接失效和配置丢失。所以在删除容器前，最好先把容器内的/var/lib/onlyoffice目录同步到宿主机备份，或者提前把数据目录也挂载出来。我建议生产环境至少挂载-v /opt/onlyoffice/data:/var/lib/onlyoffice。
4.4 第四步：验证字体进入容器
容器启动后，进入容器检查中文字体是否被fontconfig识别：
docker exec onlyoffice-docserver fc-list :lang=zh正常输出应该能看到一行行Noto Sans CJK SC的路径和字体名。如果输出为空，说明缓存还没刷新，执行：
docker exec onlyoffice-docserver fc-cache -fv docker exec onlyoffice-docserver fc-list :lang=zh我见过一种情况：fc-list :lang=zh能查到字体，但办公室里同事打开文档还是乱码。排查后发现是浏览器缓存了旧的预览结果，换个无痕窗口或清一下浏览器缓存就好了。这个问题不多，但遇到了会让人多折腾半小时。
4.5 第五步：用真实中文文档回归测试
验证字体是否真正生效，最靠谱的方法是准备一份包含中文、中英文混排、中文加粗、指定宋体/微软雅黑字体的docx文档，然后走一遍完整的在线预览和转PDF流程。
操作路径是：把docx上传到OnlyOffice集成环境中，点击在线打开，检查中文显示；再通过转换接口把docx转为PDF，下载后逐页查看中文是否清晰、加粗是否正常、有没有字符重叠或缺失。
如果这两个环节中文都正常，说明服务端字体链路已经走通了。如果在线预览正常但转PDF还有个别字符异常，多半是字体别名配置不全，看看文档里还指定了哪些字体名，在别名配置里补上对应的映射。
5. 常见问题排查与避坑记录
5.1 问题速查表
我把这个过程中能遇到的典型问题整理成一个速查表，按症状去对，基本几分钟内能定位：
| 症状 | 可能原因 | 解决办法 |
|---|---|---|
| 打开文档中文全是方块 | 容器内无中文字体 | 挂载字体目录并运行fc-cache |
| fc-list能查到字体，预览仍乱码 | 字体缓存未刷新/未重启容器 | 执行fc-cache -fv后重启容器 |
| 转换PDF中文缺字 | 字体名与文档内指定名不匹配 | 配置fontconfig字体别名映射 |
| 宿主机有字体，容器里没有 | 未挂载目录或挂载了但权限不足 | 检查-v参数，确认字体文件权限644 |
| 输入法在编辑器里打中文乱码 | 浏览器本地缺字体 | 这是客户端渲染问题，不是服务端问题 |
| 字体修改后不生效 | 缓存未刷新 | 重启容器或执行fc-cache |
| 中文文件名乱码 | 与字体无关，是文件名字符集问题 | 检查系统locale和Nginx转发编码 |
5.2 编辑界面输入中文乱码跟服务端字体没关系
这一点很容易混淆，我单独说一下。如果你在OnlyOffice在线编辑界面里，用输入法打中文字符，打出来的字在编辑器里显示成方块或乱码，这个问题跟容器里装没装中文字体没有直接关系。因为在线编辑器的输入框渲染发生在浏览器本地，它使用的是你电脑操作系统里的字体。如果你的浏览器或系统本身缺少中文字体，那不管服务端字体多全，输入法出来的字照样难看你屏幕上的显示。
服务端字体影响的是文档预览、转换、协同过程中由服务端渲染的那部分内容，以及服务端计算排版时依赖的字体度量。两者要分开排查，否则很容易陷入“装了字体怎么还乱码”的误区。判断方法很简单：乱码出现在你正在编辑的输入区域，还是出现在保存后生成的预览图/PDF里。
5.3 别忽略容器重建的数据问题
最后提醒一个容易“连带爆炸”的坑。有人按网上教程操作，写着写着让你docker rm容器重新run，如果你没做数据备份，OnlyOffice里已有的文档空间和配置就没了。OnlyOffice的文档元数据、JWT密钥、数据库都存储在容器内部的数据目录里，重建容器等于一切归零。
所以我建议生产环境启动时，就把几个关键目录挂出来：
-v /opt/onlyoffice/data:/var/lib/onlyoffice -v /opt/onlyoffice/logs:/var/log/onlyoffice -v /opt/onlyoffice/chinese-fonts:/usr/local/share/fonts/chinese:ro这样以后无论容器怎么重建，数据、日志、字体都不会丢，整套环境可以随时通过docker run命令完整复原。这也是我前面反复强调挂载方案更适合长期运行的原因。
5.4 Docker Compose场景的配置示例
如果你用的是Docker Compose管理服务，配置方式也很直观：
services: onlyoffice: image: onlyoffice/documentserver:latest container_name: onlyoffice-docserver ports: - "8080:80" volumes: - /opt/onlyoffice/data:/var/lib/onlyoffice - /opt/onlyoffice/logs:/var/log/onlyoffice - /opt/onlyoffice/chinese-fonts:/usr/local/share/fonts/chinese:ro - /opt/onlyoffice/fontconf/60-zh-alias.conf:/etc/fonts/conf.d/60-zh-alias.conf:ro restart: always执行docker compose up -d --force-recreate即可重建容器并加载新挂载。注意--force-recreate会重建容器，幸好数据目录已经挂载到宿主机，所以不会丢数据，这正好印证了刚才强调挂载数据目录的重要性。
我在实际使用中最深的体会是，处理OnlyOffice字体问题要按“先查字体、再查配置、最后查数据”的顺序排查，而不要一上来就怀疑软件坏了或者文档坏了。只要容器里fontconfig能查到中文字体，文档中指定的字体名能通过别名配置映射到实际字体文件，中文渲染就不会出大问题。最后再分享一个小技巧：如果你要部署的OnlyOffice还涉及韩文、日文文档，建议直接把Noto CJK全家族装进去，一次解决全语言场景，免得后续每个语言都来一遍今天的流程。
