先问一个场景你是不是也遇到过这种情况——后端接口、数据库、日志文件里中文都是好的一跑到导出的PDF里就成了□□□□或者Java程序生成的报表图片里全是方块排查了半天编码、UTF-8、数据库连接池都没用。这时候大多数人会去折腾locale和编码但真正的原因是这台Linux服务器上压根没有装任何中文字体。Rocky Linux和CentOS默认最小化安装只带英文相关字体系统里根本没有中文渲染需要的字形文件。今天这篇就把这事从头到尾说清楚乱码和方块的区别、在线安装、离线安装、验证方法、常见应用场景的配置以及我踩过的一些坑。1. 方块、问号、乱码的三种表现先定位到底是编码问题还是字体问题1.1 三种表现背后的真实机理先说结论字体缺失和编码错误是完全两回事处理方式天差地别。我曾经接手过一个同事的项目他说“服务器中文乱码”日志里全是“锟斤拷”“烫烫烫”这种奇怪字符他折腾了两天locale和字符集最后发现是Java连接MySQL时连接串没加characterEncodingutf8数据在写入时就已经变成乱码了。这种问题你装一百个中文字体也解决不了。日常见到的中文显示问题我习惯分成三类来看方块豆腐块/tofu显示成 □□□□ 或全是空心矩形。这是字体缺失系统没有任何一个字体包含中文字形文本内容其实没坏只是渲染不出来。这类问题的解法就是本文要讲的安装中文字体。问号????数据本身被替换成了问号。通常是写入环节的字符集设置有问题比如MySQL表字段是latin1或者Python写库时连接串没指定charsetutf8mb4。字节已经被破坏了装字体也救不回来。乱码æ–‡、淇℃伅、锟斤拷字节被错误解码。终极典型就是UTF-8编码的字节流被当成GBK显示或者反过来。这是终端、编辑器、网页的字符集声明问题也不是字体能解决的。所以遇到中文显示异常第一步先判断根因在哪个层。怎么判断很简单用cat查看文件内容、用API直接取数据如果原始数据在代码里打印出来是正常的中文但渲染成图片、PDF时变成方块那基本就是字体问题。如果打印出来本身就是乱码那就是编码链路的问题去查字符集设置别在字体上浪费时间。1.2 Linux字体体系与最小化安装“缺”了什么Linux下字体由fontconfig管理它不关心你用的是GNOME桌面还是纯命令行。只要系统里fc-list能列出来的字体所有通过fontconfig取字形的应用都能使用包括Java的渲染引擎、Chromium无头浏览器、ImageMagick、matplotlib这些。Rocky Linux 9、CentOS 7/8/9走的是RHEL系路线默认源和RHEL保持一致。最小化安装Minimal只装最基础的一组字体保证终端英文和基本符号能显示中文字体不在默认安装列表里。所以很多时候不是“你配置错了”而是系统从装好的那一刻起就根本没有中文字形文件可以调用。有人会说“我的服务器没有桌面环境要字体干什么”这是个很大的误区。虽然你在服务器上用vim看中文没问题那是终端显示的能力但只要你的业务涉及渲染也就是把文字“画”到图片、PDF、网页截图、验证码里就一定需要字体文件。无头服务器跑报表、生成分享图、做HTML转PDF全都要依赖字体。1.3 最容易栽跟头的几类业务场景根据我接触过的项目下面这几类场景和字体缺失高度相关如果你正在做或者准备做这些事建议先把字体装好场景典型表现看起来像Java报表导出JasperReports、POI导出Excel图表PDF或图片里中文是方块字体问题wkhtmltopdf、Chromium无头模式打印PDF网页转PDF后中文变方块字体问题Python matplotlib绘图、Pillow生成验证码/水印图里中文消失或方块字体问题LibreOffice headless转PDFdocx转出来中文全空字体问题容器里跑Java/Node.js应用日志正常功能正常生成文件方块镜像里没字体我之前帮人排查过一个Spring Boot生成图表图片的案例本地Windows跑得好好的部署到CentOS服务器上图片里中文全变方块。排查了半天代码最后发现就是服务器没装中文字体。所以下面的安装步骤建议当成服务器初始化的标准操作来执行。2. 在线安装中文字体默认仓库和EPEL怎么选2.1 默认源里的老牌选手文泉驿家族如果你的服务器能联网最快的方案是直接装默认源里的文泉驿字体。CentOS 7和Rocky Linux 8/9的默认仓库里都有这两个包# CentOS 7 用 yumRocky 8/9 用 dnf两者写 yum 在 Rocky 上也能用 dnf install -y wqy-microhei-fonts wqy-zenhei-fonts包名注意带-fonts后缀这是RHEL系字体包的命名习惯。装完后跑一次fc-cache -fv为什么要重建缓存fontconfig会在安装时自动跑一次但手动执行可以确认无误也不会影响系统。文泉驿微米黑wqy-microhei是黑体风格文泉驿正黑wqy-zenhei也是黑体但字形略不同。这两者的优势是体积小、默认源里有、安装零配置适合绝大多数内部系统、运维工具、报表场景。之前有个老项目生成验证码图片用的就是文泉驿跑了几年都没出过问题稳定得很。2.2 更全的Noto CJK思源黑体的Linux发行版如果业务对字形要求更高比如要覆盖生僻字、繁体中文、或者面向用户的正式产品界面我更推荐Noto Sans CJK。这是Google和Adobe联合推出的思源黑体系列在Linux里的发行版字符集覆盖非常全外形现代开源可商用。RHEL系默认仓库里没有Noto CJK需要先启用EPELdnf install -y epel-release dnf install -y google-noto-sans-cjk-fonts装完后fc-cache -fv fc-list :langzh你会看到类似Noto Sans CJK SC、Noto Sans CJK TC这样的字体族名。如果google-noto-sans-cjk-fonts这个包名找不到用dnf search noto | grep -i cjk看一下当前EPEL源里实际叫法不同版本可能拆分成更细的包。文泉驿和Noto怎么选我的建议是对比项文泉驿微米黑/正黑Noto Sans CJK获取难度默认源直接装需EPEL体积小几MB较大几十MB字符集常用简体中文够用覆盖广生僻字、繁体更全应用观感偏传统现代简洁推荐场景内部系统、运维工具、验证码对外产品、正式报表、文档转换两者并存也不冲突fontconfig会按优先级匹配。我一般习惯两套都装上日常用文泉驿顶着遇到特殊字形需求时有Noto兜底。2.3 安装失败和源失效的快速处理在线安装最常遇到的问题有三个第一是EPEL源安装慢或者超时。可以装一个epel-release后把源模板里的mirrorlist换成国内镜像这一步在网上有大量现成教程按下不表但我要提醒一句改源有风险改之前先备份/etc/yum.repos.d/下的文件。第二是字体包名在特定版本里不一致。比如有些老版本CentOS 7里wqy-microhei-fonts可能不在默认源这时候先跑yum search chinese font yum search wqy搜一下仓库里实际有什么再做安装决定。这个习惯比记住包名更重要。第三是从CentOS 7换到Rocky Linux 9后源路径变了。Rocky 9的BaseOS、AppStream、CRB原来是PowerTools这几个仓库都需要启用缺了可能导致依赖解析失败。遇到Unable to find a match时先检查dnf repolist看仓库状态再决定下一步。3. 离线环境装字体这是内网服务器最常用的路子3.1 字体文件从哪来联网下载rpm包是最稳的很多生产服务器在内网根本连不上外网。这时候我建议优先考虑rpm包离线安装而不是笨拙地去别处拷贝字体文件再上传。理由很简单rpm包能保证目录位置、文件权限、字体注册信息都正确很多细节手动拷贝容易漏。在能联网的机器上# CentOS 7 用 yumdownloader yumdownloader --resolve wqy-microhei-fonts wqy-zenhei-fonts # Rocky 8/9 用 dnf download dnf download --resolve wqy-microhei-fonts wqy-zenhei-fonts如果你的下载机和外网服务器版本不一致优先下载同版本系统的包。CentOS 7的rpm和Rocky 9的rpm不要混用尤其涉及glibc这类底层依赖时但字体包本身比较独立风险相对低不过我还是建议按版本下载。然后把rpm文件拷到内网服务器执行rpm -Uvh *.rpm或者用dnf install ./wqy-microhei-fonts-*.rpm。这种装法字体文件会被放到/usr/share/fonts/下的标准目录权限也是默认的644省去手动设置的麻烦。装完跑fc-cache -fv就行。3.2 手动放字体文件路径、权限、缓存刷新如果实在拿不到rpm包只能手动拷贝字体文件比如从其他同事机器上拿到TTF文件步骤也不复杂# 1. 创建存放目录建议放在系统级目录下 mkdir -p /usr/share/fonts/chinese # 2. 把字体文件拷贝进去 cp simhei.ttf /usr/share/fonts/chinese/ # 3. 设置权限保证所有用户可读 chmod 644 /usr/share/fonts/chinese/simhei.ttf # 4. 刷新字体缓存 fc-cache -fv这里面最容易被忽略的是权限。如果你用root上传的字体文件权限可能还是600其他服务用户比如Java进程跑的tomcat用户、Nginx的www用户读不了应用层面表现还是方块。我给过不少人排查这类问题最后都是被这一步坑了。建议手动放字体后统一chmod 644别偷懒。放哪个目录也有讲究。/usr/share/fonts/是系统级字体总目录所有用户可用/usr/local/share/fonts/是本地安装字体目录语义上是“管理员手动安装”的位置~/.fonts或~/.local/share/fonts是用户级目录只在当前用户下生效。服务器上绝大多数业务进程是系统服务所以我习惯放/usr/share/fonts/下。3.3 TTC、TTF、OTF的差异哪个更省事手动拷贝时你可能会看到ttf、ttc、otf这几种后缀TTFTrueType Font最常见的字体格式单字体文件兼容性最佳。TTCTrueType Collection多个TTF打包在一起比如Windows里的msyh.ttc同时包含雅黑和雅黑粗体。fontconfig能识别TTCfc-list里会把它拆成多个字体族显示。现代Java等引擎处理TTC也没问题但个别老版本工具兼容性差一点。OTFOpenType Font基于PostScript或TrueType轮廓现代渲染引擎都支持。老掉牙的某些Java AWT版本可能对OTF支持不好但我已经有几年没碰到这种事了。如果你不想折腾认准TTF就行。但别以为只要是TTC就不能用我实际用过微软雅黑的msyh.ttc放到Linux里fc-cache能正常识别应用里也能正常渲染。只是版权不干净详见3.4。3.4 版权提醒Windows字体别乱用于商用说到从Windows系统拷贝simhei.ttf、msyh.ttc这种操作我必须提一句版权。微软雅黑、宋体、黑体这些字体微软对它们有版权保护你本人在个人电脑上使用没问题但放到服务器上给对外业务生成图片、PDF严格来说存在版权风险企业商用场景尤其要谨慎。前两年就有公司因为把商用字体嵌入到产品里被索赔的案例金额还不小。所以给别人做项目、部署公网服务时我通常优先选择开源且可免费商用的字体Noto Sans CJK SC思源黑体GoogleAdobe出品开源商用无压力。Noto Serif CJK SC思源宋体适合正式文档。文泉驿微米黑/正黑开源历史悠久但字形偏老胜在稳妥。阿里巴巴普惠体如果业务场景允许也是个不错的免费商用选择。如果是公司内网、非商用、个人实验用Windows字体图省事问题不大但规范化的生产系统该避开还是避开。4. 装完怎么验证从命令行到真实渲染4.1 fc-list和fc-match字体到底入了库没有装完字体别急着宣布“搞定”先验证。命令就两个# 列出当前系统支持中文的字体 fc-list :langzh # 看某个字体族当前匹配到哪个字体文件 fc-match sans-serif第一个命令的输出类似/usr/share/fonts/wqy-microhei/wqy-microhei.ttc: WenQuanYi Micro Hei,文泉驿微米黑:styleRegular /usr/share/fonts/wqy-zenhei/wqy-zenhei.ttc: WenQuanYi Zen Hei,文泉驿正黑:styleRegular能看到类似内容说明字体已经进入了fontconfig的字形库。第二个命令fc-match sans-serif是看无衬线字体族默认被映射到哪个字体。中文渲染时很多软件会先请求sans-serif这个逻辑字体如果匹配结果还是英文的Liberation Sans或DejaVu Sans优先考虑加一个fontconfig别名配置优先匹配中文族见6.1。提示fc-list :langzh输出为空说明字体的lang属性注册有问题或者系统中没有包含中文的字体。还有一种情况是fc-list :langzh-cn查不到但fc-list :langzh能查到很多中文字体注册的是通用中文tag不是区域tag。4.2 用Python实测渲染一张中文图片fc-list能查到字体不代表具体应用就能正常渲染。最靠谱的验证方式是让系统真实画一张带中文的图出来。我用PythonPillow做这个测试最多python3 -c from PIL import Image, ImageDraw, ImageFont img Image.new(RGB, (400, 200), white) d ImageDraw.Draw(img) # 先用 fc-list :langzh 查出字体实际路径再替换这里的路径 font ImageFont.truetype(/usr/share/fonts/wqy-microhei/wqy-microhei.ttc, 28) d.text((50, 80), 中文测试 123, fontfont, fillblack) img.save(/tmp/chinese_test.png) 然后把/tmp/chinese_test.png下载到本地看一眼。如果图片里的中文清晰正常说明系统级别的字体供给链路没问题业务侧再乱那就是业务代码的事了。我知道你可能会说“服务器上没装Pillow怎么办”按需安装就行如果Pillow也装不上用ImageMagick的convert命令也能做类似的测试convert -background white -fill black -font /usr/share/fonts/wqy-microhei/wqy-microhei.ttc -pointsize 36 label:中文测试 /tmp/test.png4.3 为什么有些进程装完字体后还是不生效字体缓存刷新了、命令行也能查到字体了但有些服务还是显示方块这时候第一反应应该是这个服务进程是在字体安装之前启动的它没有重新加载fontconfig的字体列表。这个问题在Java服务上尤其明显JVM在启动过程中才会初始化本地字体你后续装多少字体它都不认必须重启进程。还有就是应用有自己的字体配置层比如wkhtmltopdf老版本、某些打包了自研字体的Java库它们不打系统字体主意而是从自己的安装目录读字体。这种时候不是系统字体不够是应用配置问题。我处理过的一个实例Tomcat下跑了一个Java报表服务装完字体后先systemctl restart tomcat才恢复直接重启不生效的另一个原因是存在JVM内存里的字体指纹对象不会随fc-cache更新。所以记住这条规则装完字体后所有和渲染相关的长驻进程都要重启一遍。5. 业务侧配置实际项目里怎么让字体真正被用上5.1 Java应用的中文字体加载流程与两个关键配置Java的图形渲染历来容易在服务器上出问题。Java不像原生应用直接调用系统API它通过自己的fontconfig机制把逻辑字体比如Dialog、sans-serif映射到系统字体。所以Java服务端渲染中文前提有两个系统里有中文字体这是本文前面装的。Java能正确地从系统fontconfig找到中文字体。这一步出问题通常表现为日志里没有异常但输出的PDF/图片中文全是方块。对于无头服务器没有图形界面跑Java建议在启动脚本里加上-Djava.awt.headlesstrue这个参数告诉JVM没有显示器、鼠标键盘纯后台运行。如果不加某些渲染操作会在找不到X11 DISPLAY时直接抛HeadlessException。加上之后JVM会走纯软件渲染路径配合系统字体正常工作。另一个常见坑是硬编码Windows字体名。比如代码里写new Font(微软雅黑, Font.PLAIN, 12)服务器根本没有这个名字的字体就算你装了Noto它也不叫“微软雅黑”Java会在字体列表里找一个默认替代结果就是方块或宋体回退。正确做法是代码里用逻辑字体名SansSerif、Serif、Monospaced通过fontconfig映射到中文字体。Java应用的排查思路我写在后面第6章的坑里这里先记住系统装字体 headless参数 重启JVM进程这三件套能解决绝大多数Java报表中文字体问题。5.2 wkhtmltopdf、无头Chromium和LibreOffice的字体依赖CentOS和Rocky系统上做HTML转PDF大家用得最多的是wkhtmltopdf。但这工具的老版本尤其CentOS 7里那个0.12.2.1对中文字体支持很糟不是缺字体时报错而是默认用Qt的字体栈渲染对系统字体加载不完全经常装了中文字体它也用不上。我后来逐渐把这类需求迁到无头Chromium上chromium-browser --headless --disable-gpu --no-sandbox \ --print-to-pdf/tmp/output.pdf --no-pdf-header-footer \ file:///path/to/your.htmlChromium无头模式走的是系统fontconfig只要fc-list :langzh能看到字体输出基本不会有方块。如果你不想引入Chromium也可以用LibreOffice的无头模式做文档转换也一样依赖系统字体。libreoffice --headless --convert-to pdf 中文文档.docxLibreOffice在RHEL系上依赖系统fontconfig但有人可能因为缺少某些中文字体报错或者输出空白。跑之前可以fc-match检查一下默认匹配。如果用了容器这个命令在容器里跑不要只看宿主机。5.3 Docker容器里没字体的三种解法容器化部署已经是常态了但这里有一个经常被忽略的现实基于CentOS/Rocky的官方精简镜像和最小化安装一样连中文字体都没有。更坑的是有些Alpine镜像连glibc都是替代实现字体装上能识别但某些Java程序可能还会有兼容问题。解法有三种构建镜像时直接装字体推荐FROM rockylinux:9 RUN dnf install -y wqy-microhei-fonts wqy-zenhei-fonts dnf clean all这样镜像一出厂就带字体容器起来直接用。运行时挂载系统字体目录docker run -v /usr/share/fonts:/usr/share/fonts:ro -d your-image把宿主机装好的字体目录只读挂载进容器。适合快速验证、体系结构一致的内网环境。注意:如果宿主机的字体后来被清理、升级容器的字体也会跟着变生产上稳定性不如方案1。自建基础镜像固化字体把安装字体的命令写进Dockerfilepush到私有仓库所有业务基于这个基础镜像构建。这是中大型团队最省心的方案一劳永逸。我见过不少项目宿主机字体装了但应用跑在容器里还是方块就是因为宿主机和容器是两个字体世界。所以在容器环境排中文乱码先确认你查的是容器内部的fc-list不是宿主机的。6. 我踩过的几个坑别让字体装了个寂寞6.1 装完没生效缓存、权限和路径检查要按顺序来有一次我在一个客户服务器上装好了Noto CJKfc-list :langzh也能看到但他们的Java服务就是输出方块。排查了半天发现是那个Java进程跑在一个systemd服务里而这个服务配置了ReadOnlyPaths或者ProtectSystemfull之类的沙箱选项把/usr/share/fonts给只读保护甚至屏蔽了JVM启动时根本读不到新字体。这个过程本身也是很好的排查思路先看fontconfig层、再看进程权限层、最后看应用配置层。还有一个常见问题是fc-cache跑完后应用侧显示的字体还是旧字体。这通常是fontconfig配置优先级问题。RHEL系的/etc/fonts/conf.d/目录里有一堆配置文件里面设定了字体回退的顺序。如果需要强制让某个中文字体优先可以自定义一个xml配置文件?xml version1.0? !DOCTYPE fontconfig SYSTEM fonts.dtd fontconfig alias familysans-serif/family prefer familyNoto Sans CJK SC/family /prefer /alias /fontconfig把这段放到/etc/fonts/local.conf然后fc-cache -fv会让采用“sans-serif”逻辑字体的应用优先匹配到Noto。这套玩法不常用但遇到方向问题时能救命。6.2 迁移、快照、加固脚本把字体目录弄没的糟心事字体装好后最大的敌人不是应用而是系统变更流程。我至少遇到两次这种情况上线前全部验证完毕后来运维执行了一轮安全基线加固脚本把/usr/share/fonts下的部分字体删了或者把fontconfig相关配置重置了。还有一种从虚拟机快照回滚到打快照之前的版本字体状态也跟着回滚了。吃一堑长一智后来我在做“服务器初始化规范”时会明确写一条字体安装必须写进配置管理工具Ansible、SaltStack或者初始化脚本里和创建用户、配置SSH、关闭防火墙放同一层。只要执行环境的“源”是确定的字体缺失就不会成为一个“今天好明天坏”的玄学问题。还有一点容器场景升级基础镜像时如果没有把字体装进Dockerfile而是靠手工进容器安装一重建容器就全没了。这就是5.3里说的固化进镜像/初始化脚本才是正道。6.3 字体别乱拷从版权到来源再到维护最后聊几句维护层面的体会。手动拷贝字体文件这件事我做得越来越少原因不只是版权还在于来源不可控。网上下载的所谓“XX字体包”质量参差不齐有的字体文件损坏、有的字体名乱起、有的捆绑了奇怪东西。就算能渲染以后想升级、统一管理也麻烦。而现在RHEL系和Rocky的官方仓库、EPEL里的字体包其实已经覆盖了绝大多数需求dnf管理的字体还能走系统的安全更新通道。能用包管理解决优先用包管理非得手动拷贝那就要保证来源明确、文件校验过、目录清晰、权限正确。我个人在部署新服务器时的习惯顺序是这样默认源先装文泉驿如果业务要更全的字符集再从EPEL装Noto CJK容器项目把字体写进Dockerfile有条件的生产环境做一次fc-list :langzh的巡检项纳入发布检查清单。这样下来中文乱码这档子事基本就绝迹了至少我最近两三年没再被“方块字”坑过。