PDFBox 3.0.1加载字体文件警告解析与解决咨询

警告产生的原因 #

• PDFBox 3.x字体处理逻辑升级：3.x版本会主动扫描Mac系统字体目录构建字体缓存，而2.0.x版本的扫描范围更窄、校验规则更宽松。Mac自带的LastResort-Regular.ttf这类系统 fallback 字体格式不符合3.x的新校验标准，导致加载失败触发警告。
• Format 14 cmap表解析更严格：3.x对Unicode补充平面的映射表（Format 14 cmap）做了严格解析，但部分Mac系统字体的该表实现不规范，触发“不支持Format 14 cmap表”警告；2.0.x版本会直接跳过不规范的部分，不会抛出相关告警。
• GSUB表解析增强引发SubstFormat异常：3.x强化了OpenType字体的GSUB（字形替换）表解析逻辑，部分Mac系统字体的GSUB表采用非标准实现，导致解析时抛出SubstFormat相关警告。
• Java 17权限收紧影响：Java 17限制了文件系统访问权限，3.x扫描系统字体时可能因权限不足无法读取部分字体文件，触发EOFException或加载失败警告；2.0.x版本对权限敏感度更低，不易触发这类问题。

解决方法 #

1. 禁用系统字体扫描（推荐，适配你的场景） #

既然你使用的是PDFBox内置的Standard 14字体（如TIMES_ROMAN），完全不需要依赖系统字体，直接禁用扫描即可消除所有相关警告：

// 放在代码最开头、PDFBox初始化前执行
System.setProperty("pdfbox.fontcache", "false");
System.setProperty("pdfbox.useSystemFonts", "false");

2. 指定自定义字体缓存目录 #

如果需要使用系统字体，给PDFBox指定一个有读写权限的自定义缓存目录，避免权限问题：

System.setProperty("pdfbox.fontcache", "/Users/smith/pdfbox-font-cache");

首次运行会在该目录生成字体缓存，后续运行直接读取缓存，减少扫描和加载异常。

3. 过滤日志警告 #

不想修改代码的话，可通过日志框架屏蔽PDFBox字体模块的警告。以Logback为例，在配置文件中添加：

<logger name="org.apache.pdfbox.pdmodel.font" level="ERROR"/>

4. 暂时使用2.0.x版本 #

如果以上方法都嫌麻烦，继续使用2.0.22版本也可行——该版本字体处理逻辑成熟稳定，适合对警告敏感的场景。但注意2.0.x后续会停止维护，长期来看建议适配3.x版本。

修改后的示例代码 #

public class PDFTest {
    public static void main(String[] args) throws IOException {
        // 禁用系统字体扫描和缓存
        System.setProperty("pdfbox.fontcache", "false");
        System.setProperty("pdfbox.useSystemFonts", "false");
        
        PDFont font = new PDType1Font(Standard14Fonts.FontName.TIMES_ROMAN);
        PDDocument doc = new PDDocument();
        PDPage page = new PDPage();
        PDPageContentStream content = new PDPageContentStream(doc, page);
        
        content.beginText();
        content.newLineAtOffset(10, 700);
        content.setFont(font, 12);
        content.showText("this is a test   ");
        content.newLineAtOffset(0, -15);
        content.showText("text in new line  ");
        content.endText();
        
        content.close();
        doc.addPage(page);
        doc.save("/Users/smith/file.pdf");
        doc.close(); // 记得关闭文档释放资源
    }
}

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