JavaFX 21项目打包EXE遇阻：Fat Jar失效及jlink哈希错误

一、可运行Fat Jar生成失败修复 #

JavaFX项目直接用常规Maven打包插件打Fat Jar容易踩坑，核心原因是JavaFX的模块特性和原生依赖。如果一定要做Fat Jar，得按以下方式配置：

• 用maven-shade-plugin配合javafx-maven-plugin，必须在shade插件里指定JavaFX主类，同时处理模块信息（非模块化项目要确保所有JavaFX依赖全量打包）。
• 执行mvn clean package后无法运行，先手动跑一遍定位问题：java --module-path <本地JavaFX lib路径> --add-modules javafx.controls,javafx.fxml -jar 你的jar包名.jar，看报错是缺依赖还是主类配置错误。

二、javafx:jlink哈希不匹配错误处理 #

这个问题基本是JavaFX依赖版本与JDK不兼容，或本地Maven仓库依赖包损坏导致：

• 强制版本对齐：确保POM里所有JavaFX依赖版本都是21.0.6，和OpenJDK 21.0.6完全一致，示例配置：

<dependency>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-controls</artifactId>
    <version>21.0.6</version>
</dependency>
<dependency>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-fxml</artifactId>
    <version>21.0.6</version>
</dependency>

• 清理损坏依赖：找到本地Maven仓库的org/openjfx目录直接删除，再执行mvn clean install重新拉取完整依赖。
• 检查javafx-maven-plugin配置：插件版本用0.0.8（适配JavaFX 21），指定正确的主类和模块：

<plugin>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-maven-plugin</artifactId>
    <version>0.0.8</version>
    <configuration>
        <mainClass>你的主类全路径</mainClass>
        <modules>
            <module>javafx.controls</module>
            <module>javafx.fxml</module>
        </modules>
    </configuration>
</plugin>

• 验证JAVA_HOME：执行java -version和javac -version，确认输出是OpenLogic OpenJDK 21.0.6，避免系统默认JDK干扰。

三、生成EXE的标准流程（推荐） #

Fat Jar对JavaFX项目兼容性较差，更稳定的是用官方推荐的模块化打包流程：

1. 先解决jlink的哈希问题，执行mvn clean javafx:jlink生成运行时镜像。
2. 用jpackage打包成EXE：

jpackage --type exe --name 你的应用名 --input target/jlink/image --main-jar 你的应用jar包 --main-class 你的主类全路径

嫌手动麻烦的话，可在POM中添加jpackage-maven-plugin实现自动化打包。

四、POM中常见插件说明 #

• javafx-maven-plugin：JavaFX专属插件，负责编译、运行、jlink打包，自动处理JavaFX模块依赖和运行时配置。
• maven-shade-plugin：用于打包Fat Jar，需特殊配置适配JavaFX模块系统，否则打包后无法运行。
• jpackage-maven-plugin：封装jpackage工具，将jlink生成的镜像直接打包成EXE、安装包等原生格式。

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