网页在本地显示正常,部署到阿里云服务器后却出现中文方框、字体变形,或导出的 PDF 排版错乱,原因未必在业务代码。很多服务器使用精简版 Linux 镜像,默认没有安装常用中文字体;程序找不到指定字体时,可能改用其他字体,也可能无法显示部分字符。
浏览器截图、图片合成、PDF 导出、报表生成和图表绘制,都可能调用操作系统里的字体文件。替代字体的字宽、字重不同,除了影响观感,还可能让表格换行、分页和图片布局发生变化。配置阿里云服务器字体时,要确认字体已安装、系统能够识别、应用有权限读取,并且字体许可适用于当前用途。程序如果运行在 Docker 容器中,容器里也要有字体;只在宿主机安装,通常不能解决容器内的显示问题。
先确认系统与问题范围
登录实例后,先查看操作系统版本,例如执行 cat /etc/os-release。再用 fc-list :lang=zh 检查系统已识别的中文字体。如果提示找不到命令,可能是尚未安装 fontconfig;如果命令可以运行但没有列出中文字体,则要继续检查字体文件和缓存。
还要分清系统缺字体,还是应用没有调用到已安装的字体。字体文件名、字体内部名称和程序配置里填写的名称可能不一致。可以先通过 fc-list 查看系统识别结果,再核对应用或渲染库要求的字体名称。仅凭文件名判断是否匹配,容易把问题留到运行时才发现。
安装中文字体的常见方式
通过系统软件源安装
如果发行版的软件源提供合适的中文字体包,通常可以优先使用系统包管理器安装,后续维护和升级也更方便。Debian、Ubuntu 通常使用 apt;Alibaba Cloud Linux、CentOS 系列通常使用 yum 或 dnf。先搜索当前软件源中的字体包,再根据系统版本选择字体和 fontconfig。包名会因发行版版本和软件源配置而不同,不要直接照抄另一台服务器上的命令。
安装后执行 fc-cache -f -v 刷新字体缓存,再运行 fc-list :lang=zh 确认系统能列出中文字体。若依赖字体的应用一直在运行,按服务部署方式重启进程,让它重新读取字体配置。只刷新缓存却不重启应用,有时仍会看到旧的渲染结果。
手动安装字体文件
软件源没有所需字体时,可以上传已获授权的字体文件。常见的系统级目录是 /usr/share/fonts,也可以按实际需求安装到特定用户的字体目录。建议为项目建立独立子目录,并记录字体来源、版本和授权范围,方便后续排查和更新。
上传后检查文件及上级目录的读取权限,再执行 fc-cache -f -v。通常应用只需要读取字体,不必给字体目录开放写权限。选择字体时,也要确认程序支持相应格式,并查看随附的许可说明。字体的下载许可、服务器端使用许可,以及用它生成图片或文档后的分发许可,可能不是一回事;来源不明或授权范围不清楚的字体,不宜直接用于商业网站和生产系统。
报表导出的中文为什么会变成方框
例如,某企业把 Java 报表服务部署到阿里云 Linux 实例后,英文显示正常,PDF 里的中文却成了方框。开发环境使用桌面系统,预装了中文字体;生产环境采用精简镜像,没有对应字库。排查时,先用 fc-list 确认实例上没有可用的中文字体,再安装经确认适用于该业务的字体,刷新缓存并重启报表服务。
字体安装后,中文仍未正常显示。继续检查发现,报表配置填写的是字体文件名,而渲染库需要的是字体内部名称。调整配置后问题才解决。处理这类故障时,要分别确认系统或运行环境里有字体,以及应用能够按正确名称调用它。上线前可以抽查中文、数字、标点和特殊字符,并检查 PDF 的对齐、换行和分页是否符合预期。
Docker、权限与缓存排错
- 容器内找不到字体:在镜像构建阶段安装字体,或把字体文件和相关配置纳入镜像。宿主机已安装,并不代表容器里的程序可以使用。
- 应用用户无法读取:检查字体文件及上级目录的权限,确认服务运行用户有读取权限。一般不需要开放写权限。
- 新增字体后效果没变:运行
fc-cache -f -v刷新缓存,并按应用的运行方式重启相关进程。 - 配置了字体仍然报错:用
fc-list查看系统识别的名称,再按应用或渲染库的要求填写,不要只根据文件名配置。 - 线上与本地版式不同:核对字体版本、应用依赖、浏览器或渲染引擎版本,以及容器镜像。把字体和配置纳入部署流程,比在不同环境中临时补文件更容易保持一致。
把字体配置纳入部署流程
生产环境里,字体安装不应依赖运维人员临时登录服务器操作。可以在初始化脚本或镜像构建流程中记录系统版本、字体包或文件版本、安装位置、验证命令和授权信息。部署后检查关键字体是否可见;如果字体文件较大,也要考虑镜像体积和后续更新成本。不同环境随意替换字体,可能让网页、图片和文档版式发生变化。
阿里云服务器不会替应用自动选好合适的字体。遇到中文方框或排版异常,可以依次检查系统是否识别字体、应用名称是否匹配、服务用户是否有读取权限、缓存是否刷新,以及字体是否安装在实际运行环境中。按这几项逐一排查,通常比先改业务代码更容易定位问题。