Docker在GitHub Actions构建时无法加载字体的问题排查

问题原因 #

Alpine系统中，fontconfig不会自动扫描新添加的字体并生成缓存。本地macOS构建环境可能因Docker的默认行为自动完成了缓存更新，但GitHub Actions的Ubuntu环境下无此触发逻辑，导致fc-list无法识别新复制的字体。

修复方法 #

修改Dockerfile，在安装fontconfig后手动执行字体缓存更新命令：

修改后的Dockerfile内容：

FROM alpine:3.18

ENV LANG=en_US.UTF-8 \
    LC_ALL=en_US.UTF-8 \
    TZ=Asia/Shanghai

WORKDIR /app
ENV ROCKET_ADDRESS=0.0.0.0
RUN mkdir -p /usr/share/fonts/ && mkdir -p /app/config/ && mkdir -p /root/.ssh
COPY ./config/font/HelveticaNeueLTPro-Md.otf /usr/share/fonts/
RUN apk update && apk add fontconfig \
    && fc-cache -fv /usr/share/fonts/
CMD sh -c 'while true; do sleep 1; done'

关键说明 #

• fc-cache -fv 命令会强制刷新（-f）并输出详细日志（-v）指定目录下的字体缓存，确保新复制的字体被fontconfig识别。
• 将fc-cache与apk add放在同一个RUN指令中，可减少镜像层数，符合Docker构建最佳实践。

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