Ubuntu下启动JavaFX Fat Jar应用报错的求助及问题原因说明

问题场景 #

• 技术栈：Java 17、JavaFX 18，模块化项目，使用Maven Shade插件构建Fat Jar
• 异常表现：
  • 应用在Mac、Windows系统可正常启动
  • 通过mvn javafx:run命令能正常运行
  • 在Ubuntu系统执行java -jar fat.jar时抛出以下错误：

Graphics Device initialization failed for :  es2, sw
Error initializing QuantumRenderer: no suitable pipeline found
java.lang.RuntimeException: java.lang.RuntimeException: Error initializing QuantumRenderer: no suitable pipeline found

排查过程 #

• 排除环境安装问题：mvn javafx:run可正常运行，说明Ubuntu的Java环境无异常，该命令直接基于Maven仓库依赖构建模块/类路径启动，与Jar启动的依赖逻辑一致
• 排除依赖未打包问题：JavaFX依赖均来自Maven仓库且已被打包进Fat Jar，非JDK内置组件

问题根源与解决方案 #

• 问题根源：一直使用Mac环境下生成的旧Fat Jar文件。JavaFX包含平台相关的native渲染库，Mac打包的Jar仅包含适配Mac的native组件，在Ubuntu系统中无法找到匹配的渲染管道，从而触发报错。
• 解决方案：在Ubuntu环境下重新执行Maven构建命令（如mvn clean package），生成适配Linux平台的Fat Jar后，再执行java -jar fat.jar即可正常启动应用。

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