使用Maven Shade打包JavaFX项目为Fat Jar遇运行异常求助

现象原因 #

• JRE无法启动Jar：Java 11及以后版本中，JavaFX不再是JDK/JRE的内置组件。纯净版JRE不包含JavaFX运行时类库，启动时找不到javafx.application.Application等核心类，因此抛出异常；而你的JDK可能捆绑了JavaFX或本地环境配置了依赖路径，所以能正常运行。
• Unsupported JavaFX configuration警告：Maven Shade插件只是简单合并所有依赖类到一个Jar，未遵循JavaFX的模块化规范。JavaFX本身是命名模块（javafx.*），但打包后所有类被放入未命名模块，不符合JavaFX运行要求，触发警告。

解决办法 #

方案1：调整Maven Shade配置（适配JRE+消除警告） #

修改pom.xml中的Shade插件配置，添加模块属性并指定正确主类：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.4.1</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
            <configuration>
                <transformers>
                    <!-- 指定非Application的Main类作为入口 -->
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                        <mainClass>com.yourpackage.Main</mainClass>
                    </transformer>
                    <!-- 合并服务配置，适配JavaFX模块系统 -->
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
                </transformers>
                <!-- 排除签名文件，避免打包冲突 -->
                <filters>
                    <filter>
                        <artifact>*:*</artifact>
                        <excludes>
                            <exclude>META-INF/*.SF</exclude>
                            <exclude>META-INF/*.DSA</exclude>
                            <exclude>META-INF/*.RSA</exclude>
                        </excludes>
                    </filter>
                </filters>
            </configuration>
        </execution>
    </executions>
</plugin>

确保Main类代码正确：

public class Main {
    public static void main(String[] args) {
        javafx.application.Application.launch(App.class, args);
    }
}

打包后，Jar会包含所有JavaFX依赖，纯净JRE也能运行（注意：部分老旧JRE可能不兼容，建议使用对应版本的JRE）。

方案2：使用官方推荐的JavaFX打包工具（更稳定） #

Shade并非JavaFX官方推荐的打包方式，更推荐以下两种工具：

• jlink生成自定义JRE镜像：
  在pom.xml添加javafx-maven-plugin配置：

  <plugin>
      <groupId>org.openjfx</groupId>
      <artifactId>javafx-maven-plugin</artifactId>
      <version>0.0.8</version>
      <configuration>
          <mainClass>com.yourpackage.App</mainClass> <!-- 直接用继承Application的类 -->
          <launcher>distcalc</launcher> <!-- 启动脚本名称 -->
          <jlinkImageName>distcalc-app</jlinkImageName> <!-- 生成的镜像目录 -->
      </configuration>
  </plugin>
  

  执行命令：mvn javafx:jlink，生成的镜像目录自带JRE和启动脚本，用户无需额外安装Java环境。

• jpackage生成原生安装包：
  先执行mvn package生成Jar，再用jpackage命令（JDK 16+支持）生成exe/dmg/deb等安装包：

  jpackage --name distcalc --input target --main-jar distcalc-1.0.jar --main-class com.yourpackage.Main --type exe
  

  生成的安装包可直接分发，用户安装后点击即可运行，无需关心Java环境。

额外注意事项 #

确保pom.xml中JavaFX依赖指定了对应操作系统的分类器：

<dependencies>
    <dependency>
        <groupId>org.openjfx</groupId>
        <artifactId>javafx-controls</artifactId>
        <version>21.0.1</version>
        <classifier>win</classifier> <!-- 替换为mac/linux适配你的开发环境 -->
    </dependency>
    <dependency>
        <groupId>org.openjfx</groupId>
        <artifactId>javafx-fxml</artifactId>
        <version>21.0.1</version>
        <classifier>win</classifier>
    </dependency>
</dependencies>

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