【实战】 容器中Spring boot项目 Graphics2D 画图中文乱码解决方案

场景

架构：spring boot
容器技术：docker
服务器：阿里云
开发环境：windows10 + IDEA

一、问题

服务器中出现Graphics2D 画图中文乱码
本地环境运行正常

二、原因

spring boot 容器中没有安装中文字体

三、解决方案

安装字体即可

四、实战

Step 1：服务器安装中文字体

Step 1-1：安装常见中文字体

Noto 系列字体 (Google 提供)

sudo apt update
sudo apt install fonts-noto-cjk  # 包含简体中文、繁体中文、日文和韩文字体
sudo fc-cache -fv  # 更新字体缓存

Step 1-2： 查看已安装的中文字体

# 查看所有已安装的中文字体
fc-list :lang=zh

# 查看特定字体族
fc-list | grep "WenQuanYi"
fc-list | grep "Noto Sans CJK"

Step 2：Spring boot - 引用字体

Step 2-1：字体复制到resources下

src/main/resources/fonts/opentype/noto/NotoSansCJK-Bold.ttc
字体可以在1-2服务器路径中copy出来

Step 2-2：代码中引用

ClassPathResource resource = new ClassPathResource("fonts/opentype/noto/NotoSansCJK-Bold.ttc");

    public static Font loadCustomFont() {
        try {
            // 从 resources 加载字体文件流
            ClassPathResource resource = new ClassPathResource("fonts/opentype/noto/NotoSansCJK-Bold.ttc");
            InputStream fontStream = resource.getInputStream();

            // 创建字体（TrueType 或 OpenType 字体使用 Font.TRUETYPE_FONT）
            Font font = Font.createFont(Font.TRUETYPE_FONT, fontStream);

            // 设置字体大小和样式（可选）
            font = font.deriveFont(Font.BOLD, 120f); // 120f 为字号

            return font;
        } catch (Exception e) {
            e.printStackTrace();
            // 回退到默认字体
            return new Font("Arial", Font.BOLD, 30);
        }
    }

Step 3：spring boot 容器安装字体

Step 3-1：修改 Dockerfile

目的：
1、JDK8 更换 AdoptOpenJDK 的 Debian 基础镜像更容易安装字体。
2、安装字体管理系统

整改前：

FROM docker.io/library/openjdk:8
RUN ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime
COPY ./config /config
COPY ./lib /lib
ADD xxx.jar xxx.jar
ENTRYPOINT ["java","-Dloader.path=/lib","-jar","xxx.jar"]

整改后：

FROM  adoptopenjdk/openjdk8:jdk8u292-b10-debian
RUN ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime && \
    apt-get update && \
    apt-get install -y fontconfig && \
    rm -rf /var/lib/apt/lists/* && \
    fc-cache -fv 
COPY ./config /config
COPY ./lib /lib
ADD xxx.jar xxx.jar
ENTRYPOINT ["java","-Dloader.path=/lib","-jar","xxx.jar"]

Step 3-2：修改 docker-compose.yaml

目的：挂在系统字体到镜像中 - /usr/share/fonts:/usr/share/fonts

Step 4：重新构建镜像

# 进入docker-compose.yaml 所在目录
cd /xxx/xxx

# 重新构建镜像
docker-compose up -d --build

五、附录：指令详解

这些指令是在基于 Debian/Ubuntu 的 Linux 系统中用于字体管理的常见操作组合。下面是对每条指令及其组合作用的详细说明：

1. apt-get install -y fontconfig

• 作用：安装 fontconfig 字体管理系统
• 详细说明：
  • apt-get install：Debian/Ubuntu 系统的包安装命令
  • -y：自动确认（跳过 “Do you want to continue? [Y/n]” 的交互提示）
  • fontconfig：Linux 系统核心字体配置工具，提供：
    • 字体扫描和缓存管理
    • 字体匹配和替换规则
    • 系统级和用户级字体配置
• 典型输出：

  Reading package lists...
  Building dependency tree...
  Installing fontconfig (2.13.1-4.2)...
  

2. rm -rf /var/lib/apt/lists/*

• 作用：清理 APT 软件包缓存
• 详细说明：
  • /var/lib/apt/lists/：存储 apt update 下载的软件包元数据
  • rm -rf：递归强制删除
  • 目的：
    • 减小 Docker 镜像体积（可节省 20-50MB 空间）
    • 避免使用过时的软件包列表
  • 安全影响：
    • 不会删除已安装的软件
    • 下次执行 apt update 会重新生成列表

3. fc-cache -fv

• 作用：重建字体缓存
• 详细说明：
  • fc-cache：fontconfig 的缓存生成工具
  • -f：强制重建（即使缓存已存在）
  • -v：显示详细处理信息（verbose）
  • 典型输出：

    /usr/share/fonts: caching, new cache contents: 6 fonts, 0 dirs
    /usr/local/share/fonts: caching, new cache contents: 0 fonts, 0 dirs
    

  • 缓存位置：~/.cache/fontconfig/ 和 /var/cache/fontconfig/

组合指令的整体作用

apt-get install -y fontconfig && \
rm -rf /var/lib/apt/lists/* && \
fc-cache -fv

1. 安装字体配置系统（必需依赖）
2. 清理临时文件（优化镜像体积）
3. 初始化字体缓存（使新安装的字体立即可用）

典型使用场景

在 Dockerfile 中：

RUN apt-get update && \
    apt-get install -y fontconfig && \
    rm -rf /var/lib/apt/lists/* && \
    fc-cache -fv

• 注意事项：
  • 必须先在同一个 RUN 中执行 apt-get update，否则可能安装失败
  • && 确保前一条命令成功才执行后续命令
  • \ 是 Dockerfile 中的换行符

在普通 Linux 系统中：

sudo apt update && \
sudo apt install -y fontconfig && \
sudo rm -rf /var/lib/apt/lists/* && \
sudo fc-cache -fv

故障排查

如果命令失败：

1. 检查网络连接（ping archive.ubuntu.com）
2. 确认有足够的磁盘空间（df -h）
3. 查看详细错误（去掉 -y 参数或添加 -o Debug::pkgProblemResolver=1）

延伸知识

• 字体安装后通常需要重启应用才能生效
• 用户级字体缓存存放在 ~/.cache/fontconfig/
• 查看已加载字体：fc-list