openhtmltopdf在Docker容器中运行时无法加载字体问题求解

这个报错和字体文件本身有效性、代码逻辑无关，核心是Docker容器内的运行环境和本地环境存在差异，具体触发点通常是两类：

• 你使用的是精简版JDK基础镜像（比如Alpine版JDK、Slim版JDK、自定义裁剪的jlink镜像），这类镜像默认移除了Java AWT/Java2D 图形渲染依赖的原生系统库（freetype、fontconfig、X11无头渲染相关组件），甚至部分裁剪过的JRE直接去掉了java.desktop模块里的字体处理实现。openhtmltopdf加载TTF字体时会调用Java2D底层的原生字体解析接口，依赖缺失时就会抛出IO异常，误报为字体文件无效。
• JVM默认没有开启无头模式，在无图形界面的容器环境里尝试加载X11图形组件失败，连带导致字体读取流程中断。

本地开发环境一般是完整安装的JDK，系统自带图形渲染相关依赖，所以不会触发这个问题。

按实施成本从低到高排序：

1. 开启JVM无头模式
   在容器启动的JVM参数中添加-Djava.awt.headless=true，强制Java2D走无图形界面依赖的无头渲染逻辑，不需要修改代码或镜像，大部分场景下加完这个参数就能恢复正常。Spring Boot项目也可以直接在配置文件中添加该参数，或者写入Dockerfile的启动命令中。
2. 给精简镜像补全缺失的系统依赖
   如果开启无头模式后仍然报错，说明镜像缺少字体渲染相关的系统库，根据你用的基础镜像类型执行对应安装命令：
   • 若使用Alpine系基础镜像：

     apk add --no-cache fontconfig freetype ttf-dejavu
     

   • 若使用Debian/Ubuntu系Slim基础镜像：

     apt-get update && apt-get install -y --no-install-recommends fontconfig libfreetype6 && rm -rf /var/lib/apt/lists/*
     

   如果你是用jlink自定义裁剪的JRE镜像，确保构建时包含了java.desktop模块，不要把字体相关的实现裁掉。
3. 校验类路径字体文件完整性（低概率排查项）
   可以在字体加载逻辑前加一行日志，打印读取到的字体资源大小，确认Docker构建时没有因为Maven/Gradle的资源过滤配置损坏TTF文件、或者漏把字体文件打进Jar包：

   // 打印字体文件大小，和本地原文件大小比对
   println("Loaded font size: ${regularFont.contentLength()}")
   

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