Spring Boot 3.3.x生成Excel遇Fontconfig head is null错误的解决方法

问题原因 #

Docker容器默认使用的基础镜像（如openjdk:alpine或官方spring-boot镜像）多为极简环境，缺少fontconfig工具和系统字体，导致Java的AWT模块无法正常获取字体配置，进而触发Apache POI生成Excel时的字体错误。

解决方案（基于Spring Boot Maven插件构建） #

方案1：自定义Dockerfile，安装字体和fontconfig #

Spring Boot Maven插件支持指定自定义Dockerfile，操作步骤：

1. 在项目根目录创建Dockerfile，内容如下：

# 基于Eclipse Temurin JRE镜像（兼容Spring Boot 3.3.x）
FROM eclipse-temurin:17-jre-alpine

# 安装fontconfig工具和基础字体
RUN apk add --no-cache fontconfig ttf-dejavu

# 更新字体缓存
RUN fc-cache -f -v

# 复制构建好的jar包（插件会自动替换占位符）
ARG JAR_FILE=target/*.jar
COPY ${JAR_FILE} app.jar

# 应用启动命令
ENTRYPOINT ["java","-jar","/app.jar"]

2. 在pom.xml的Spring Boot Maven插件配置中指定使用该Dockerfile：

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <docker>
            <dockerfile>Dockerfile</dockerfile>
        </docker>
    </configuration>
</plugin>

3. 重新构建镜像：执行mvn spring-boot:build-image

方案2：嵌入字体到应用，配置Java使用内嵌字体 #

无需修改基础镜像，将字体打包到应用中让Java直接加载：

1. 在项目src/main/resources下创建fonts目录，放入常用字体文件（如DejaVuSans.ttf）。
2. 添加字体加载组件，在应用启动时注册字体：

import java.awt.Font;
import java.io.InputStream;
import javax.annotation.PostConstruct;
import org.springframework.stereotype.Component;

@Component
public class CustomFontLoader {

    @PostConstruct
    public void loadEmbeddedFont() {
        try (InputStream fontStream = getClass().getResourceAsStream("/fonts/DejaVuSans.ttf")) {
            Font customFont = Font.createFont(Font.TRUETYPE_FONT, fontStream).deriveFont(Font.PLAIN, 12);
            java.awt.GraphicsEnvironment.getLocalGraphicsEnvironment().registerFont(customFont);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

3. 构建镜像时字体文件会被打包进jar，Java启动后自动加载该字体，摆脱对系统字体的依赖。

方案3：临时禁用AWT字体查找（不推荐） #

仅适合临时测试场景，通过JVM参数跳过字体检查：
在pom.xml的Spring Boot Maven插件中添加JVM参数：

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <jvmArguments>-Djava.awt.headless=true -Dsun.java2d.font.disable=true</jvmArguments>
    </configuration>
</plugin>

注意：此方案可能导致Excel字体显示异常（如默认字体缺失），不建议生产环境使用。

内容的提问来源于stack exchange，提问作者Gavi