使用Opensagres和Apache POI将DOCX转PDF在Docker环境出现字符缺失问题

根因说明 #

该问题本质是Docker Linux环境下PDF转换库未正确加载支持目标字符集的字体，且默认字体回退策略未生效导致的字符渲染失败。 #

可行方案 #

• 方案1：显式为转换库注册自定义字体路径
  多数PDF转换库不会自动扫描项目内导入的TTF字体路径，需手动配置注册。以你当前使用的PdfConverter为例，可在构造PdfOptions时新增字体注册逻辑：

  try {
        PdfOptions options = PdfOptions.create();
        // 新增：注册classpath下存放字体的目录，第二个参数设为true允许自动替代缺字字体系列
        options.fontProvider(new ClasspathFontProvider("your-font-dir/", true));
        PdfConverter.getInstance().convert(firstDoc, out, options);
    } catch (IOException ex) {
        throw new IllegalArgumentException("Conversion failed.");
    }
    return prepareResponseEntity(out);
  

  如果底层依赖documents4j实现转换，需在构造转换器时指定字体目录。

• 方案2：更换为全字符集开源商用免费字体
  部分裁剪版Liberation Sans字体本身未覆盖波罗的海字符、西里尔字符集，可更换为Google Noto Sans字体，该字体支持几乎所有全球语言字符，遵守SIL Open Font License，商用无版权风险。将DOCX模板字体统一替换为Noto Sans，同时将全系列TTF文件放入项目字体目录即可。

• 方案3：Docker镜像层面配置系统字体
  在Dockerfile中添加开源全字集字体安装和缓存配置，无需使用微软字体：
  基于Debian/Ubuntu基础镜像：

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

  基于Alpine基础镜像：

  RUN apk add --no-cache \
      font-noto \
      fontconfig \
      && fc-cache -fv
  

  镜像构建完成后可在容器内执行fc-list命令验证字体是否被系统正常识别。

• 方案4：强制开启字体回退机制
  若转换底层依赖Apache POI+PDFBox实现，可手动开启缺字自动回退配置，指定默认 fallback 字体为你导入的全字符集字体，避免缺字时直接丢弃字符。

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