PDFBox 3.x启动调用API时大量警告问题求助（Docker环境）

1. 字体缓存重建警告（大量新字体发现） #

原因 #

PDFBox默认扫描系统所有字体目录，Docker镜像若预装全量Noto等大型字体包，会触发缓存重建，耗时且产生警告。

解决方案 #

• 指定自定义字体目录：在代码中配置FileSystemFontProvider仅扫描指定目录，避免遍历系统所有字体：

  // 创建自定义字体提供者，仅加载指定目录的字体
  FileSystemFontProvider fontProvider = new FileSystemFontProvider();
  fontProvider.addDirectory(new File("/path/to/your/custom/fonts"));
  // 设置PDFBox使用该字体提供者
  PDFRenderer renderer = new PDFRenderer(document);
  renderer.setFontProvider(fontProvider);
  

• 禁用系统字体扫描：通过JVM参数或代码关闭默认系统字体加载：

  // 关闭默认系统字体加载
  System.setProperty("pdfbox.fontcache", "false");
  // 或启动时添加JVM参数：-Dpdfbox.fontcache=false
  

• 预生成字体缓存：在Docker构建阶段提前生成字体缓存，避免运行时重建：

  RUN java -cp your-app.jar org.apache.pdfbox.pdmodel.font.FileSystemFontProvider
  

2. Unknown substFormat: 0/256警告 #

原因 #

部分TTF字体的GlyphSubstitutionTable使用了PDFBox暂不支持的格式，解析时抛出警告。

解决方案 #

• 调整日志级别：将org.apache.fontbox.ttf.GlyphSubstitutionTable的日志级别设为ERROR，屏蔽警告输出（以Logback为例）：

  <logger name="org.apache.fontbox.ttf.GlyphSubstitutionTable" level="ERROR"/>
  

• 替换问题字体：若这些字体非业务必需，替换为PDFBox兼容的字体版本。

3. Noto系列字体加载失败（EOFException） #

原因 #

Docker镜像中的部分Noto字体文件损坏或不完整，导致PDFBox读取时抛出EOF异常。

解决方案 #

• 删除损坏字体：在Dockerfile中删除报错的字体文件：

  RUN rm /usr/share/fonts/truetype/noto/NotoSansPahawhHmong-Regular.ttf
  

• 精简Noto字体包：仅安装业务所需的Noto字体子集，减少扫描范围和出错概率。
• 重新安装完整字体包：若需保留这些字体，重新安装完整的Noto字体包：

  RUN apt-get remove -y fonts-noto && apt-get install -y fonts-noto --reinstall
  

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