使用Maven构建的JavaFX jar包运行时报NoClassDefFoundError如何解决

你当前的Maven配置仅编译了项目自身代码，没有将依赖的JavaFX类库打包到最终输出的jar包中，运行时JVM无法找到JavaFX核心类，因此抛出NoClassDefFoundError异常。

1. 补全JavaFX依赖 #

你当前仅引入了javafx-fxml和javafx-controls组件，缺失JavaFX运行必需的基础组件，需要在<dependencies>标签内补全如下内容：

<!-- 补全javafx-base依赖 -->
<dependency>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-base</artifactId>
    <version>16</version>
</dependency>
<dependency>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-base</artifactId>
    <version>16</version>
    <classifier>win</classifier>
</dependency>
<dependency>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-base</artifactId>
    <version>16</version>
    <classifier>mac</classifier>
</dependency>
<dependency>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-base</artifactId>
    <version>16</version>
    <classifier>linux</classifier>
</dependency>
<!-- 补全javafx-graphics依赖 -->
<dependency>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-graphics</artifactId>
    <version>16</version>
</dependency>
<dependency>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-graphics</artifactId>
    <version>16</version>
    <classifier>win</classifier>
</dependency>
<dependency>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-graphics</artifactId>
    <version>16</version>
    <classifier>mac</classifier>
</dependency>
<dependency>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-graphics</artifactId>
    <version>16</version>
    <classifier>linux</classifier>
</dependency>
<!-- 补全javafx-controls无classifier依赖 -->
<dependency>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-controls</artifactId>
    <version>16</version>
</dependency>

2. 替换打包插件为maven-shade-plugin #

maven-jar-plugin默认不会将第三方依赖打包到jar包中，你需要使用maven-shade-plugin生成包含所有依赖的Fat Jar。将<build>标签内原有maven-jar-plugin配置删除，新增如下插件配置：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.2.4</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
            <configuration>
                <transformers>
                    <!-- 合并服务配置，解决JavaFX模块冲突 -->
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
                    <!-- 配置主类 -->
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                        <mainClass>mvc.Launcher</mainClass>
                    </transformer>
                </transformers>
            </configuration>
        </execution>
    </executions>
</plugin>

3. 验证主类结构 #

确保你的mvc.Launcher类是独立的启动类，不要继承javafx.application.Application，正确结构如下：

package mvc;
// 你的实际Application实现类
import mvc.YourApplication;

public class Launcher {
    public static void main(String[] args) {
        YourApplication.main(args);
    }
}

4. 重新构建运行 #

执行mvn clean package命令构建项目，构建完成后在target目录下找到名称格式为TP_2-1.0-SNAPSHOT-jar-with-dependencies.jar的文件，使用java -jar命令运行该文件即可。

• 运行jar包的JDK版本需要和项目编译版本保持一致，需使用JDK15及以上版本
• 最终生成的Fat Jar兼容Windows、Mac、Linux三个平台，无需用户单独配置JavaFX环境

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