如何为JavaFX+Spring Boot应用制作跨平台（Windows/MacOS/Linux）安装包

我是JavaFX新手，开发了一个作为STOMP Websocket客户端的JavaFX & Spring Boot应用，已打包为jar文件且可通过Java命令正常运行。现需将其封装为包含JRE的Windows/Mac/Linux安装包，以便其他电脑可轻松安装。我曾尝试使用JPackage的教程，但安装后的程序无法运行。以下是我的pom.xml和主类代码：

pom.xml 代码 #

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.1</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.my-group</groupId>
    <artifactId>my-app</artifactId>
    <version>1.0</version>
    <name>my-app</name>

    <properties>
        <java.version>17</java.version>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.apache.httpcomponents.client5</groupId>
            <artifactId>httpclient5</artifactId>
            <version>5.2.1</version>
        </dependency>
        <dependency>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-controls</artifactId>
            <version>19.0.2.1</version>
        </dependency>
        <dependency>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-fxml</artifactId>
            <version>19.0.2.1</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-security</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-websocket</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.security</groupId>
            <artifactId>spring-security-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

主类代码 #

package com.mygroup.myapp;

import javafx.application.Application;
import javafx.application.Platform;
import javafx.fxml.FXMLLoader;
import javafx.scene.Parent;
import javafx.scene.Scene;
import javafx.stage.Stage;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ConfigurableApplicationContext;

import java.awt.*;

@SpringBootApplication
public class MyApplication extends Application {

    private ConfigurableApplicationContext applicationContext;
    private Parent rootNode;

    public static void main(String[] args) {
        if (!SystemTray.isSupported()) {
            System.setProperty("java.awt.headless", "false");
        }
        Application.launch(args);
    }

    @Override
    public void init() throws Exception {
        applicationContext = SpringApplication.run(MyApplication.class);
        FXMLLoader fxmlLoader = new FXMLLoader(getClass().getResource("/login.fxml"));
        fxmlLoader.setControllerFactory(applicationContext::getBean);
        rootNode = fxmlLoader.load();
    }

    @Override
    public void start(Stage primaryStage) {
        Platform.setImplicitExit(false);

        primaryStage.setResizable(false);
        primaryStage.setScene(new Scene(rootNode));
        primaryStage.show();
    }

    @Override
    public void stop() {
        applicationContext.close();
        Platform.exit();
    }
}

问题排查与解决步骤 #

1. 修正pom.xml配置 #

原pom.xml缺少JavaFX打包相关配置，导致JPackage无法正确识别JavaFX模块。添加JavaFX Maven插件，并明确指定主类：

<build>
    <plugins>
        <!-- 保留原有Spring Boot插件，添加主类配置 -->
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <excludes>
                    <exclude>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                    </exclude>
                </excludes>
                <mainClass>com.mygroup.myapp.MyApplication</mainClass>
            </configuration>
        </plugin>
        <!-- 添加JavaFX打包插件 -->
        <plugin>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-maven-plugin</artifactId>
            <version>0.0.8</version>
            <configuration>
                <mainClass>com.mygroup.myapp.MyApplication</mainClass>
                <launcher>my-app</launcher>
                <jlinkImageName>my-app-image</jlinkImageName>
            </configuration>
        </plugin>
    </plugins>
</build>

2. 生成自定义JRE镜像 #

JavaFX是模块化框架，默认JRE不包含其模块，需用jlink生成包含依赖模块的自定义JRE：
执行Maven命令：

mvn clean javafx:jlink

执行完成后，target/my-app-image目录下会生成包含JRE和应用的可运行镜像。

3. 使用JPackage生成对应平台安装包 #

根据目标系统执行以下命令，替换path/to/your/icon为实际图标路径（可选）：

Windows 生成EXE安装包

jpackage --name MyApp --input target/my-app-image/bin --main-jar my-app.jar --main-class com.mygroup.myapp.MyApplication --type exe --win-menu --win-shortcut

macOS 生成DMG安装包

jpackage --name MyApp --input target/my-app-image/bin --main-jar my-app.jar --main-class com.mygroup.myapp.MyApplication --type dmg --mac-package-name MyApp

Linux 生成DEB/RPM安装包

# DEB包
jpackage --name MyApp --input target/my-app-image/bin --main-jar my-app.jar --main-class com.mygroup.myapp.MyApplication --type deb --linux-menu-group Applications

# RPM包
jpackage --name MyApp --input target/my-app-image/bin --main-jar my-app.jar --main-class com.mygroup.myapp.MyApplication --type rpm --linux-menu-group Applications

4. 常见问题修复 #

• 程序无法启动：检查--main-class的全类名是否正确，确认jlink镜像包含javafx.controls、javafx.fxml模块，可通过jlink --list-modules --module-path target/my-app-image/lib验证。
• JavaFX组件不显示：确保自定义JRE包含所有JavaFX依赖模块，javafx-maven-plugin会自动处理，若手动执行jlink需添加--add-modules javafx.controls,javafx.fxml参数。
• 系统托盘异常：将System.setProperty("java.awt.headless", "false")移至SpringApplication.run()之前执行，避免Spring默认启用headless模式。

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