如何修复打包JavaFX应用为JAR时出现的java.lang.NoClassDefFoundError错误

问题原因 #

你遇到的java.lang.NoClassDefFoundError: javafx/application/Application错误，本质是JavaFX从JDK 11开始成为模块化依赖库，普通的JAR打包方式无法正确处理JavaFX的模块依赖——即使你把JavaFX的JAR添加到工件中，JVM运行时也无法通过传统classpath加载这些模块化的类。

解决方案 #

方法1：使用IntelliJ IDEA的JavaFX专属打包工具（最简便） #

• 打开File > Project Structure > Artifacts，删除你之前创建的普通JAR工件。
• 点击+ > JavaFx Application > From module...，选择你的主模块，指定主类（比如com.example.song_finder_fx.App）。
• 在弹出的配置窗口中，确认JavaFX SDK路径正确指向你安装的JavaFX 21-ea+24。
• 点击OK保存配置，然后执行Build > Build Artifacts，选择对应的JavaFX工件进行构建。
  这种方式会自动处理模块依赖，生成的可执行文件（或带依赖的JAR）可以直接运行。

方法2：使用构建工具（Maven/Gradle）打包（适合持续集成场景） #

如果你的项目用Maven或Gradle管理，推荐用官方插件处理JavaFX打包：

Maven

在pom.xml中添加javafx-maven-plugin配置：

<build>
    <plugins>
        <plugin>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-maven-plugin</artifactId>
            <version>0.0.8</version>
            <configuration>
                <mainClass>com.example.song_finder_fx.App</mainClass>
                <modules>
                    <module>javafx.controls</module>
                    <module>javafx.fxml</module>
                </modules>
            </configuration>
        </plugin>
    </plugins>
</build>

然后执行命令：

• 生成可执行JAR：mvn javafx:jar
• 生成包含JRE的原生镜像（推荐，无需用户安装JavaFX）：mvn javafx:jlink

Gradle

在build.gradle中添加OpenJFX插件：

plugins {
    id 'java'
    id 'org.openjfx.javafxplugin' version '0.0.13'
}

javafx {
    version = '21-ea+24'
    modules = ['javafx.controls', 'javafx.fxml']
}

mainClassName = 'com.example.song_finder_fx.App'

然后执行命令：

• 生成可执行JAR：gradle jar
• 生成原生镜像：gradle jlink

方法3：手动指定模块路径运行（临时方案） #

如果不想重新打包，可以在运行JAR时手动指定JavaFX的模块路径：

java --module-path "/path/to/javafx-sdk-21-ea+24/lib" --add-modules javafx.controls,javafx.fxml -jar your-app.jar

注意替换/path/to/javafx-sdk-21-ea+24/lib为你本地JavaFX SDK的lib目录路径。这种方式需要用户自己配置JavaFX环境，不适合分发应用。

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