“Fontconfig head is null”错误的终极排查与修复

最新推荐文章于 2026-06-30 04:58:52 发布

原创

最新推荐文章于 2026-06-30 04:58:52 发布 · 2k 阅读

标签

#java

一、背景

Java应用在开发环境idea上运行得好好的，但是一部署到Linux服务器上运行生成excel模板就崩溃了，日志里赫然躺着

Servlet.service() for servlet [dispatcherServlet] in context with path [] threw exception [Request processing failed: java.lang.RuntimeException: Fontconfig head is null, check your fonts or fonts configuration] with root cause

java.lang.RuntimeException: Fontconfig head is null, check your fonts or fonts configuration

这段令人头疼的错误，就是前段时间Java应用部署时碰到的问题，花了几个小时，最终终于彻底解决，下面将详细记录解决的过程以及原因。这个错误并非代码之过，而是服务器环境的”字体“导致的。（文末附上测试工程代码，并在第三部分详细介绍如何通过拷贝的方式安装fontconfig）

二、快速解决方案

以ubuntu系统为例，通常是因为系统中缺少fontconfig组件。fontconfig是一个字体配置和管理系统，它的核心职责是为应用程序提供可用字体列表，并告诉它们如何正确渲染和显示这些字体，可以把它想象成操作系统的”字体管家“或者”字体调度中心“。

fontconfig的安装步骤：

#更新软件包列表
sudo apt update

#安装fontconfig
sudo apt install fontconfig

#完全重新安装
sudo apt remove --purge fontconfig
sudo apt autoremove
sudo apt install fontconfig

安装之后，可以使用fc的命令去验证安装的情况

#检查版本
fc-list --version

#列出所有已安装字体
fc-list

验证没问题之后，正常再执行excel文件生成就不会报错了。

三、fontconfig详解

fontconfig是一个字体配置和管理系统，安装之后，fontconfig会持续扫描系统中特定的字体目录（如/usr/share/fonts/, /usr/local/share/fonts/,~/.local/share/fonts/,~/.fonts/), 建立一个所有已安装字体的数据库。

当安装一个新字体，并运行fc-cache命令，fontconfig会立即将其纳入管理范围。

fontconfig相关命令如下：

fc-list：列出fontconfig所知的所有字体
fc-match: 测试fontconfig如何匹配一个字体
fc-cache: 手动重建字体缓存。在安装新字体后，
有时需要运行此命令（sudo fc-cache -fv)来让系统立即识别新字体
fc-conflist: 列出当前加载的配置信息

如果服务器在局域网中，无法连接互联网的，可以通过两种方式进行fontconfig安装，一是通过有互联网的机器wget下载fontconfig安装包；二是拷贝已经安装fontconfig机器上的安装信息。接下来详细介绍第二种方式，这种方式对于网络隔离的特别有用。

fontconfig的安装路径，主要有以下这些：

（1）二进制文件  /usr/bin/
-rwxr-xr-x  1 root root       22760 Mar 23  2022 fc-cache*       用于构建字体缓存
-rwxr-xr-x  1 root root       18664 Mar 23  2022 fc-cat*         用于读取缓存信息
-rwxr-xr-x  1 root root       14568 Mar 23  2022 fc-conflist*    用于列出配置
-rwxr-xr-x  1 root root       14568 Mar 23  2022 fc-list*        用于列出可用字体
-rwxr-xr-x  1 root root       14568 Mar 23  2022 fc-match*