基于htmltopdf-java的wkhtmltopdf在Spring Boot Docker部署中运行异常

问题根因 #

报错java.lang.NoClassDefFoundError: Could not initialize class io.woo.htmltopdf.wkhtmltopdf.WkHtmlToPdf不是类路径缺少依赖导致的，本质是WkHtmlToPdf类的静态初始化块执行失败，JVM在后续访问该类时抛出了该错误，具体触发原因有几个：

• 系统原生二进制不兼容：1.0.8版本的htmltopdf-java会在初始化时自动释放jar包内置的、针对glibc系统编译的wkhtmltopdf可执行文件到临时目录并加载，而你当前用的Alpine基础镜像采用musl libc，无法正常运行这份glibc编译的二进制文件。
• 手动安装的系统wkhtmltopdf不生效：你通过apk安装的Alpine版wkhtmltopdf和库内置的版本路径、加载逻辑完全不匹配，库默认优先加载自身携带的二进制，不会主动调用系统路径下的程序，装了也起不到替代作用。
• Dockerfile本身存在多处错误：
  • 基础指令语法错误：开头FROM FROM openjdk:8-jre-alpine重复写了FROM关键字，正常镜像构建流程会直接报错
  • 运行环境缺失：openjdk:8-jre-alpine镜像本身不内置Tomcat，不存在/opt/tomcat目录、catalina.sh启动脚本，所有路径和启动配置都是无效的
  • 容器环境和本地运行环境差异过大：本地Ubuntu是glibc系统，容器内是musl的Alpine环境，运行时的系统库完全不匹配，自然会出现初始化失败。

解决方案 #

优先方案：换用glibc基础镜像（和本地Ubuntu运行环境完全一致，零代码改动） #

优先选用Debian系的JDK+Tomcat基础镜像，和库内置的wkhtmltopdf二进制完全兼容，不需要手动安装wkhtmltopdf本体，只需要补全运行必需的系统依赖即可，修正后的Dockerfile参考：

# 修正语法错误，选用自带Tomcat的Debian系glibc镜像
FROM tomcat:8.5-jre8

ARG WAR_FILE

# 安装wkhtmltopdf运行必需的系统依赖（不需要安装wkhtmltopdf本体）
# 包含PDF渲染需要的图形库、基础字体、中文字体（避免生成的PDF中文乱码）
RUN apt-get update && apt-get install -y --no-install-recommends \
    fontconfig \
    libjpeg62-turbo \
    libpng16-16 \
    libxrender1 \
    libxtst6 \
    xfonts-base \
    xfonts-75dpi \
    fonts-wqy-zenhei \
    && rm -rf /var/lib/apt/lists/*

# 拷贝应用war包到Tomcat部署目录
COPY ${WAR_FILE} /usr/local/tomcat/webapps/dodo.war

# 启动Tomcat服务
ENTRYPOINT ["catalina.sh", "run"]

该方案和本地Ubuntu的运行逻辑完全一致，不需要修改业务代码，库初始化时直接可以正常加载内置的wkhtmltopdf二进制，不会再出现类初始化失败的问题。

备选方案：如果必须使用Alpine镜像 #

需要放弃使用库内置的二进制，手动安装Alpine适配的wkhtmltopdf，并通过代码指定库调用系统安装的可执行文件，需要的依赖配置参考：

FROM openjdk:8-jre-alpine

ARG WAR_FILE

# 安装Alpine版本wkhtmltopdf、模拟X11环境的组件、字体依赖
RUN apk add --no-cache \
    wkhtmltopdf \
    xvfb-run \
    fontconfig \
    ttf-dejavu \
    ttf-wqy-zenhei \
    && rm -rf /var/cache/apk/*

# 补全Tomcat运行环境
RUN apk add --no-cache tomcat8
# 指定wkhtmltopdf的系统路径，供Java库初始化时读取
ENV WKHTMLTOPDF_SYSTEM_PATH=/usr/bin/xvfb-run /usr/bin/wkhtmltopdf

WORKDIR /usr/share/tomcat8
COPY ${WAR_FILE} /usr/share/tomcat8/webapps/dodo.war
ENTRYPOINT ["catalina.sh", "run"]

注意该方案需要修改业务代码中WkHtmlToPdf的初始化逻辑，强制指定使用系统路径下的wkhtmltopdf可执行文件，否则库仍然会尝试加载内置的不兼容二进制，改动成本更高。

额外配置说明 #

如果需要生成包含中文、特殊格式的PDF，需要在镜像中额外安装对应语言的字体包，避免出现方块字、乱码问题；如果不需要特殊字体，至少要安装fontconfig基础库，否则wkhtmltopdf渲染时会因为找不到字体配置直接崩溃。

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