JavaFX Jar在Linux/Raspberry Pi运行失败，寻求解决方案

问题概述 #

• 开发的HelloFX.jar在Windows JDK21环境运行正常，但在Linux和树莓派的JDK21环境执行java -jar HelloFX.jar时报错，核心提示为无合适渲染管线。
• 已排查一个月未解决，其他Java程序在Linux/树莓派上运行正常。
• 项目用IntelliJ IDE构建，相关POM配置、HelloApplication.java、HelloView.FXML、Main.java文件已提供。

错误信息 #

jibon@jibon:~/Desktop $ java -jar HelloFX.jar 
Nov 27, 2023 1:24:11 PM com.sun.javafx.application.PlatformImpl startup
WARNING: Unsupported JavaFX configuration: classes were loaded from 'unnamed module @9efff14'
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
    at com.sun.javafx.tk.quantum.QuantumRenderer.getInstance(QuantumRenderer.java:283)
    at com.sun.javafx.tk.quantum.QuantumToolkit.init(QuantumToolkit.java:253)
    at com.sun.javafx.tk.Toolkit.getToolkit(Toolkit.java:263)
    at com.sun.javafx.application.PlatformImpl.startup(PlatformImpl.java:290)
    at com.sun.javafx.application.PlatformImpl.startup(PlatformImpl.java:162)
    at com.sun.javafx.application.LauncherImpl.startToolkit(LauncherImpl.java:651)
    at com.sun.javafx.application.LauncherImpl.launchApplication1(LauncherImpl.java:671)
    at com.sun.javafx.application.LauncherImpl.lambda$launchApplication$2(LauncherImpl.java:196)
    at java.base/java.lang.Thread.run(Thread.java:1583)
Caused by: java.lang.RuntimeException: Error initializing QuantumRenderer: no suitable pipeline found
    at com.sun.javafx.tk.quantum.QuantumRenderer$PipelineRunnable.init(QuantumRenderer.java:95)
    at com.sun.javafx.tk.quantum.QuantumRenderer$PipelineRunnable.run(QuantumRenderer.java:125)
    ... 1 more
Exception in thread "main" java.lang.RuntimeException: No toolkit found
    at com.sun.javafx.tk.Toolkit.getToolkit(Toolkit.java:275)
    at com.sun.javafx.application.PlatformImpl.startup(PlatformImpl.java:290)
    at com.sun.javafx.application.PlatformImpl.startup(PlatformImpl.java:162)
    at com.sun.javafx.application.LauncherImpl.startToolkit(LauncherImpl.java:651)
    at com.sun.javafx.application.LauncherImpl.launchApplication1(LauncherImpl.java:671)
    at com.sun.javafx.application.LauncherImpl.lambda$launchApplication$2(LauncherImpl.java:196)
    at java.base/java.lang.Thread.run(Thread.java:1583)

解决方案 #

1. 补充平台特定的JavaFX依赖 #

JavaFX渲染依赖平台本地库，你的jar包可能仅包含Windows平台依赖，需在POM中添加Linux/ARM（树莓派）的分类器依赖：

<dependencies>
    <!-- Linux x64平台依赖 -->
    <dependency>
        <groupId>org.openjfx</groupId>
        <artifactId>javafx-controls</artifactId>
        <version>21</version>
        <classifier>linux-x86_64</classifier>
    </dependency>
    <dependency>
        <groupId>org.openjfx</groupId>
        <artifactId>javafx-fxml</artifactId>
        <version>21</version>
        <classifier>linux-x86_64</classifier>
    </dependency>
    <!-- 树莓派ARM64平台依赖 -->
    <dependency>
        <groupId>org.openjfx</groupId>
        <artifactId>javafx-controls</artifactId>
        <version>21</version>
        <classifier>linux-aarch64</classifier>
    </dependency>
    <dependency>
        <groupId>org.openjfx</groupId>
        <artifactId>javafx-fxml</artifactId>
        <version>21</version>
        <classifier>linux-aarch64</classifier>
    </dependency>
</dependencies>

2. 使用JavaFX Maven插件构建 #

用javafx-maven-plugin自动打包多平台本地库，避免手动处理依赖问题，POM添加插件配置：

<build>
    <plugins>
        <plugin>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-maven-plugin</artifactId>
            <version>0.0.8</version>
            <configuration>
                <mainClass>你的主类全路径（如com.example.Main）</mainClass>
                <platforms>
                    <platform>
                        <name>win</name>
                    </platform>
                    <platform>
                        <name>linux</name>
                    </platform>
                    <platform>
                        <name>linux-aarch64</name>
                    </platform>
                </platforms>
            </configuration>
        </plugin>
    </plugins>
</build>

执行mvn javafx:jar构建，生成的jar会包含所有指定平台的本地库。

3. 强制指定渲染管线（临时测试） #

树莓派环境可尝试强制使用软件渲染启动：

java -Dprism.order=sw -jar HelloFX.jar

或尝试启用ES2渲染：

java -Dprism.order=es2 -jar HelloFX.jar

4. 安装系统依赖库 #

Linux/树莓派需安装JavaFX依赖的系统库：

• Ubuntu/Debian系：

sudo apt install libopenjfx-java libopenjfx-jni

• 树莓派：

sudo apt install openjfx

5. 修复模块化配置 #

错误提示Unsupported JavaFX configuration: classes were loaded from 'unnamed module'，需添加module-info.java声明模块依赖：

module com.example.hellofx {
    requires javafx.controls;
    requires javafx.fxml;
    opens com.example.hellofx to javafx.fxml;
    exports com.example.hellofx;
}

构建时确保模块路径正确，javafx-maven-plugin会自动处理模块化打包。

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