mp-java/docs/chinese-font-fix-guide.md

捐款证书中文乱码修复指南

问题描述

生成的捐款证书图片中，中文字符显示为乱码或方块，影响证书的正常使用。

问题示例：https://file-s209.shoplnk.cn/poster/10547/pay/2536.jpg?v=0409

根本原因

1. 系统缺少中文字体：Docker容器（Alpine Linux）默认不包含中文字体
2. 字体回退机制不完善：当找不到中文字体时，回退到的默认字体不支持中文
3. 字体检测不够严格：原代码只检测单个汉字，可能导致误判

修复方案

方案一：重新构建Docker镜像（推荐）

1. 使用更新后的Dockerfile

项目的 Dockerfile 已经更新，新增了中文字体支持：

# 安装必要工具和中文字体支持
RUN apk add --no-cache wget fontconfig ttf-dejavu && \
    # 下载并安装文泉驿微米黑字体（更好的中文支持）
    wget -O /tmp/wqy-microhei.ttc https://github.com/anthonyfok/fonts-wqy-microhei/raw/master/wqy-microhei.ttc && \
    mkdir -p /usr/share/fonts/truetype/wqy && \
    mv /tmp/wqy-microhei.ttc /usr/share/fonts/truetype/wqy/ && \
    # 刷新字体缓存
    fc-cache -fv

2. 重新构建镜像

# 打包项目
mvn clean package -DskipTests

# 构建Docker镜像
docker build -t websoft-api:latest .

# 停止旧容器
docker stop websoft-api-container

# 删除旧容器
docker rm websoft-api-container

# 启动新容器
docker run -d \
  --name websoft-api-container \
  -p 9200:9200 \
  -v /path/to/uploads:/app/uploads \
  -v /path/to/logs:/app/logs \
  -e SPRING_PROFILES_ACTIVE=prod \
  websoft-api:latest

方案二：在运行中的容器内安装字体

如果不方便重新构建镜像，可以在运行中的容器内安装字体：

# 进入容器
docker exec -it -u root websoft-api-container sh

# 安装字体工具
apk add --no-cache fontconfig ttf-dejavu

# 下载中文字体
wget -O /tmp/wqy-microhei.ttc https://github.com/anthonyfok/fonts-wqy-microhei/raw/master/wqy-microhei.ttc

# 创建字体目录
mkdir -p /usr/share/fonts/truetype/wqy

# 移动字体文件
mv /tmp/wqy-microhei.ttc /usr/share/fonts/truetype/wqy/

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

# 验证字体安装
fc-list :lang=zh

# 退出容器
exit

# 重启应用（不重启容器）
docker exec websoft-api-container pkill -f "java.*app.jar"

方案三：使用其他基础镜像

如果Alpine Linux的字体支持仍有问题，可以考虑切换到Debian基础镜像：

FROM eclipse-temurin:17-jdk

# 安装中文字体
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    fonts-wqy-microhei \
    fonts-wqy-zenhei \
    fontconfig && \
    fc-cache -fv && \
    rm -rf /var/lib/apt/lists/*

代码改进说明

1. 增强的字体检测逻辑

// 检查多个中文字符，确保字体真正支持中文
if (font.canDisplay('中') && font.canDisplay('文')) {
    return font;
}

2. macOS字体优先级调整

String[] chineseFonts = {
    "PingFang SC",         // 苹方 (macOS) - 优先使用
    "STHeiti",             // 华文黑体 (macOS)
    "Hiragino Sans GB",    // 冬青黑体 (macOS)
    "Microsoft YaHei",     // 微软雅黑 (Windows)
    // ...
};

3. 多层字体回退机制

// 第一层：预定义字体列表
// 第二层：Java逻辑字体（SansSerif, Serif等）
// 第三层：明确的错误提示

4. 详细的日志输出

System.out.println("✓ 成功使用字体: " + fontName + " (字号: " + fontSize + ")");
System.err.println("✗ 严重警告：系统中没有找到任何支持中文的字体！");

验证修复

1. 查看容器日志

docker logs -f websoft-api-container

成功加载字体时会看到：

✓ 成功使用字体: PingFang SC (字号: 26)
✓ 成功使用字体: PingFang SC (字号: 22)

2. 测试证书生成

调用API生成新的证书，检查中文是否正常显示。

3. 验证字体列表

在容器内执行：

fc-list :lang=zh

应该能看到已安装的中文字体列表。

macOS开发环境说明

如果在macOS上开发，系统已经包含以下中文字体：

• PingFang SC（苹方，推荐）
• STHeiti（华文黑体）
• Hiragino Sans GB（冬青黑体）

代码已优化为优先使用这些字体。

故障排查

问题1：Docker镜像构建失败

原因：网络问题导致字体下载失败
解决：

# 使用国内镜像或手动下载字体
wget https://ghproxy.com/https://github.com/anthonyfok/fonts-wqy-microhei/raw/master/wqy-microhei.ttc

问题2：容器重启后字体丢失

原因：使用方案二安装的字体未持久化
解决：使用方案一重新构建镜像

问题3：日志显示找不到字体

原因：字体安装未生效或路径错误
解决：

# 检查字体文件是否存在
docker exec websoft-api-container ls -la /usr/share/fonts/truetype/wqy/

# 重建字体缓存
docker exec -u root websoft-api-container fc-cache -fv

问题4：仍然显示乱码

原因：可能是图片已缓存
解决：

1. 清除浏览器缓存
2. 删除旧的证书图片文件
3. 重新生成证书（URL参数v会自动更新）

性能优化建议

1. 字体缓存：首次加载后，字体会被JVM缓存，后续生成速度更快
2. 字体大小：文泉驿微米黑字体文件约10MB，不会显著增加镜像大小
3. 镜像层优化：字体安装合并到一个RUN命令中，减少镜像层数

相关文件

• /src/main/java/com/gxwebsoft/bszx/service/impl/BszxPayServiceImpl.java - 捐款证书生成逻辑
• /src/main/java/com/gxwebsoft/bszx/service/impl/BszxBmServiceImpl.java - 报名证书生成逻辑
• /Dockerfile - Docker镜像构建配置

技术支持

如果问题仍未解决，请提供以下信息：

1. Docker镜像构建日志
2. 容器启动日志（包含字体加载信息）
3. 生成的证书图片链接
4. 系统环境信息（docker version, docker info）