使用PDFBox将PDF转图片时字体样式失效问题求助

问题根源 #

容器环境中PDFBox未正确识别已安装的微软核心字体（msttcorefonts），默认使用LiberationSans作为Helvetica-Bold、Helvetica、Courier-Bold、Courier的fallback字体，导致粗体样式丢失；而Windows环境默认包含这些字体，因此正常运行。

解决方案 #

1. 确保容器内字体缓存已刷新 #

安装msttcorefonts后，必须强制刷新系统字体缓存，否则系统和PDFBox无法识别新安装的字体：

fc-cache -fv /usr/share/fonts/msttcorefonts/

执行后可通过以下命令验证字体是否被识别：

# 检查Arial系列字体（对应Helvetica）
fc-list | grep -i "arial"
# 检查Courier New系列字体（对应Courier）
fc-list | grep -i "courier"

若输出中包含arialbd.ttf（Arial Bold）、arial.ttf（Arial）、courbd.ttf（Courier New Bold）、cour.ttf（Courier New），则字体已被系统识别。

2. 在代码中强制指定字体映射 #

直接在代码中为PDFBox指定字体替换规则，不依赖系统字体缓存，确保字体被正确加载：

boolean isDoubleSide = false; // 方法参数
FontProvider fontProvider = new FontProvider();

// 手动添加对应字体文件路径
try {
    // 映射Helvetica-Bold到Arial Bold
    fontProvider.addFont(new File("/usr/share/fonts/msttcorefonts/arialbd.ttf"));
    // 映射Helvetica到Arial
    fontProvider.addFont(new File("/usr/share/fonts/msttcorefonts/arial.ttf"));
    // 映射Courier-Bold到Courier New Bold
    fontProvider.addFont(new File("/usr/share/fonts/msttcorefonts/courbd.ttf"));
    // 映射Courier到Courier New
    fontProvider.addFont(new File("/usr/share/fonts/msttcorefonts/cour.ttf"));
} catch (IOException e) {
    e.printStackTrace();
}

try (PDDocument pdDocument = Loader.loadPDF(new File("path/to/pdffile"))) {
    // 为PDF文档设置自定义字体提供者
    pdDocument.setFontProvider(fontProvider);
    PDFRenderer pdfRenderer = new PDFRenderer(pdDocument);
    
    for (int page = 0; page < pdDocument.getNumberOfPages(); ++page) {
        BufferedImage bufferedImage = pdfRenderer.renderImageWithDPI(page, 203);
        String imageFileName = isDoubleSide 
            ? Paths.get("path/to/imagefile", random_str + "_" + (page + 1) + ".jpeg").toString()
            : Paths.get("path/to/imagefile", sOutFileNameBase + ".jpeg").toString();
        ImageIO.write(bufferedImage, "jpeg", new File(imageFileName));
    }
} catch (IOException e) {
    e.printStackTrace();
}

注意：需确保代码中指定的字体文件路径与容器内实际路径一致，若msttcorefonts安装路径不同，需对应调整。

3. 修正Docker镜像的字体安装步骤 #

若使用自定义Docker镜像，需在Dockerfile中完成字体安装并刷新缓存，示例：

# 基于CentOS/RHEL/Fedora镜像
FROM centos:7

# 安装依赖并下载微软核心字体
RUN yum install -y wget && \
    wget https://downloads.sourceforge.net/project/mscorefonts2/rpms/msttcore-fonts-installer-2.6-1.noarch.rpm && \
    rpm -i msttcore-fonts-installer-2.6-1.noarch.rpm && \
    # 刷新字体缓存
    fc-cache -fv && \
    # 清理临时文件
    rm -f msttcore-fonts-installer-2.6-1.noarch.rpm && \
    yum clean all

4. 验证字体加载日志（可选） #

开启PDFBox的DEBUG日志，确认字体是否被正确加载：
添加日志配置（以Log4j2为例）：

<Configuration status="INFO">
    <Loggers>
        <Logger name="org.apache.pdfbox" level="DEBUG"/>
        <Root level="INFO">
            <AppenderRef ref="Console"/>
        </Root>
    </Loggers>
</Configuration>

运行程序后，查看日志中是否包含类似Loaded font Arial Bold的条目，确认字体加载成功。

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