Ubuntu/CentOS/openEuler｜全系列Linux一键安装中文字体解决方案（解决中文方框乱码）

Ubuntu/CentOS/openEuler｜全系列Linux一键安装中文字体解决方案

- 一、前言
- - [1.1 故障根因](#1.1 故障根因)
  - [1.2 字体选型](#1.2 字体选型)
  - [1.3 依赖工具](#1.3 依赖工具)
- 二、全局通用命令（全系统复用）
- 三、分发行版安装脚本（root权限执行）
- - [3.1 Ubuntu / Debian 系列](#3.1 Ubuntu / Debian 系列)
  - [3.2 CentOS 系列](#3.2 CentOS 系列)
  - - [👉 CentOS7（yum包管理器）](#👉 CentOS7（yum包管理器）)
    - [👉 CentOS8+ / RockyLinux（dnf包管理器）](#👉 CentOS8+ / RockyLinux（dnf包管理器）)
  - [3.3 国产openEuler欧拉系统](#3.3 国产openEuler欧拉系统)
- 四、故障排查
- - [故障1：fc-list :lang=zh 无中文输出](#故障1：fc-list :lang=zh 无中文输出)
  - 故障2：字体已安装，业务依旧中文方框
  - 故障3：欧拉安装cjkuni字体提示包不存在
- 五、运维部署速查表

一、前言

1.1 故障根因

Linux业务服务（Java报表、图片水印、PDF导出）中文乱码方框，核心两点：①系统未预装CJK标准中文字体 ②新增字体后未刷新系统字体缓存。

1.2 字体选型

全网运维通用选型：文泉驿开源字体，商用免费无版权风险，适配所有Linux发行版

wqy-microhei 文泉驿微米黑：体积小、渲染稳定，生产首选，适配报表、截图、打印
wqy-zenhei 文泉驿正黑：字符最全，适配PDF排版、页面中文渲染

1.3 依赖工具

系统字体管理依赖：fontconfig 工具包

✅ 筛选查看中文字体：fc-list :lang=zh

✅ 刷新字体缓存：fc-cache -fv

二、全局通用命令（全系统复用）

bash 复制代码

# 1、精准过滤查看系统所有中文字体
# :lang=zh 筛选中文语种字体，过滤英文字体，排查效率更高
fc-list :lang=zh

# 2、强制刷新系统字体缓存【必执行】
# -f：强制重建字体缓存
# -v：可视化输出执行日志，方便排查报错
fc-cache -fv

三、分发行版安装脚本（root权限执行）

3.1 Ubuntu / Debian 系列

bash 复制代码

# 更新系统软件源索引，修复依赖缺失、下载失败问题
sudo apt-get update

# 批量安装字体组件（安装字体管理工具+两套开源中文字体+可选微软雅黑字体）
# fontconfig：系统字体核心管理工具
# ttf-mscorefonts-installer：可选，集成微软雅黑/宋体Windows商用字体
# fonts-wqy-microhei：文泉驿微米黑
# fonts-wqy-zenhei：文泉驿正黑
sudo apt-get install -y fontconfig ttf-mscorefonts-installer fonts-wqy-microhei fonts-wqy-zenhei

# 刷新字体缓存
fc-cache -fv

# 校验中文字体安装结果
fc-list :lang=zh

命令执行内容

bash 复制代码

root@ubuntu:/home/projects/workflow-engine# fc-list :lang=zh
/usr/share/fonts/wqy-microhei/wqy-microhei.ttc: WenQuanYi Micro Hei Mono,文泉驛等寬微米黑,文泉驿等宽微米黑:style=Regular
/usr/share/fonts/wqy-zenhei/wqy-zenhei.ttc: WenQuanYi Zen Hei Sharp,文泉驛點陣正黑,文泉驿点阵正黑:style=Regular
/usr/share/fonts/wqy-microhei/wqy-microhei.ttc: WenQuanYi Micro Hei,文泉驛微米黑,文泉驿微米黑:style=Regular
/usr/share/fonts/wqy-zenhei/wqy-zenhei.ttc: WenQuanYi Zen Hei Mono,文泉驛等寬正黑,文泉驿等宽正黑:style=Regular
/usr/share/fonts/wqy-zenhei/wqy-zenhei.ttc: WenQuanYi Zen Hei,文泉驛正黑,文泉驿正黑:style=Regular

3.2 CentOS 系列

👉 CentOS7（yum包管理器）

bash 复制代码

# 安装字体管理库 + 文鼎CJK中文字体 + 文泉驿微米黑
# cjkuni-ukai-fonts：文鼎楷体
# cjkuni-uming-fonts：文鼎宋体
sudo yum install -y fontconfig cjkuni-ukai-fonts cjkuni-uming-fonts wqy-microhei-fonts

# 刷新字体缓存
fc-cache -fv

# 校验中文字体
fc-list :lang=zh

👉 CentOS8+ / RockyLinux（dnf包管理器）

bash 复制代码

sudo dnf install -y fontconfig cjkuni-ukai-fonts cjkuni-uming-fonts wqy-microhei-fonts
fc-cache -fv
fc-list :lang=zh

3.3 国产openEuler欧拉系统

部署避坑 ：openEuler官方源无 cjkuni 文鼎字体包，复用CentOS命令直接安装报错，仅支持文泉驿字体！

bash 复制代码

# 欧拉专属字体安装命令
dnf install -y fontconfig wqy-microhei-fonts wqy-zenhei-fonts

# 刷新缓存，业务服务才可识别字体
fc-cache -fv

# 核验中文字体
fc-list :lang=zh

安装字体命令

刷新字体缓存，业务服务才可识别字体

核验中文字体

四、故障排查

故障1：fc-list :lang=zh 无中文输出

未安装fontconfig依赖：重新执行对应系统完整安装脚本
未执行缓存刷新：务必执行 fc-cache -fv
软件源失效：更换阿里云/清华国内镜像源

故障2：字体已安装，业务依旧中文方框

未重启业务进程：Java、微服务、绘图服务重启加载字体
代码字体名称错误：业务代码固定填写字体名 WenQuanYi Micro Hei
系统编码非UTF-8，执行编码修复脚本：

bash 复制代码

# 配置系统全局中文UTF8编码
# 生成系统中文UTF-8编码
sudo locale-gen zh_CN.UTF-8

# 写入全局环境变量
echo "export LANG=zh_CN.UTF-8" >> /etc/profile

# 生效环境配置
source /etc/profile

故障3：欧拉安装cjkuni字体提示包不存在

欧拉系统原生剔除文鼎CJK字体，属于系统特性，直接使用上文欧拉专属安装脚本即可。

五、运维部署速查表

✅ 通用核验：fc-list :lang=zh

✅ 通用生效：fc-cache -fv

操作系统发行版	默认包管理器	推荐安装字体	部署禁忌/注意事项（实测保真）	生产最优字体
Ubuntu/Debian	apt	文泉驿+微软兼容字体	内网服务器必须apt update；外网可直接安装	文泉驿微米黑
CentOS7	yum	CJK文鼎+文泉驿字体	默认yum源自带字体包，无需提前更新源	文泉驿微米黑
CentOS8/RockyLinux	dnf	CJK文鼎+文泉驿字体	yum为dnf软链接，系统原生优先使用dnf执行安装	文泉驿微米黑
openEuler欧拉	dnf	仅文泉驿全系字体	官方源无cjkuni文鼎字体，执行安装直接报错，禁止使用	文泉驿微米黑