Spire Doc Free 3.9.0部署无头服务器报NoClassDefFoundError是什么原因？

报错成因 #

• 核心原因是Spire Doc底层依赖Java AWT图形类库完成字体加载、文档排版计算，你部署的无头Linux服务器默认没有启用Java无头运行模式，也没有配套的图形环境组件，导致com.spire.doc.packages.sprDGC类初始化时加载AWT组件失败，最终抛出NoClassDefFoundError。
• 本地开发环境自带完整的桌面图形组件，类初始化过程没有阻碍，所以运行完全正常。

解决方案 #

方案1：开启Java无头运行模式 #

启动Spring Boot项目时添加对应JVM参数即可，无需额外安装软件依赖：

java -Djava.awt.headless=true -jar 你的项目jar包名称.jar

如果使用Docker部署，可以直接在Dockerfile的ENTRYPOINT配置中添加参数：

ENTRYPOINT ["java", "-Djava.awt.headless=true", "-jar", "/app/你的项目jar包名称.jar"]

方案2：安装服务器缺失的字体组件 #

部分场景下开启无头模式后还会因为缺失通用字体、中文字体导致后续文档排版异常，可以同步安装字体包：

• Debian/Ubuntu系统执行命令：

apt-get update && apt-get install -y fontconfig libfreetype6 fonts-dejavu-core fonts-wqy-zenhei

• CentOS/RHEL系统执行命令：

yum install -y fontconfig freetype dejavu-sans-fonts wqy-zenhei-fonts

安装完成后执行fc-cache --force刷新系统字体缓存，再重启项目即可生效。

方案3：升级Spire Doc版本 #

如果上述配置完成后仍有报错，可以尝试升级Spire Doc Free到更高的稳定版本，3.9.0属于较老的版本，后续官方版本对无头运行环境的适配做了大量优化，可规避很多已知兼容问题。

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