针对maven javafx项目在intellij idea中打包为可执行jar文件时遇到的`noclassdeffounderror`和`securityexception`等问题，本教程详细介绍了如何通过配置`maven-assembly-plugin`生成包含所有依赖的“胖jar”，并提供了正确的命令行运行方式，包括指定javafx模块路径和添加模块参数，确保javafx应用程序能够成功启动。
在基于Maven的JavaFX项目中，将应用程序打包成可执行的JAR文件并在不同环境中顺利运行，常常会遇到一些挑战。尤其是当JavaFX作为模块化库引入时，其运行时环境的配置显得尤为重要。本文旨在提供一套行之有效的解决方案，帮助开发者克服在IntelliJ IDEA中构建和运行JavaFX可执行JAR包时遇到的常见问题。
常见问题分析
开发者在尝试运行通过java -jar yourproject.jar命令启动的JavaFX应用程序时，可能会遇到以下两种典型错误：
Error: Could not find or load main class ... Caused by: java.lang.NoClassDefFoundError: javafx/application/Application 这个错误是最常见的，它表明Java虚拟机（JVM）在运行时无法找到JavaFX应用程序所需的关键类，例如javafx.application.Application。这通常是因为JavaFX模块并未被正确地包含在JAR包中，或者在运行JAR时没有通过 --module-path 和 --add-modules 参数正确指定JavaFX运行时模块。自Java 11起，JavaFX已从JDK中移除，需要作为外部模块引入。
Error: A JNI error has occurred, please check your installation and try again Exception in thread "main" java.lang.SecurityException: Invalid signature file digest for Manifest main attributes 此错误通常发生在通过IntelliJ IDEA的Artifacts功能生成JAR包，或使用不当的打包策略时。它可能与JAR文件的签名验证失败有关，尤其是在合并多个带有签名的依赖（如某些第三方库）时，可能会导致Manifest文件中的摘要信息不一致，从而触发安全异常。
解决方案：构建“胖JAR”并正确运行
解决上述问题的关键在于两个方面：一是使用Maven插件将所有项目依赖（包括JavaFX模块的类文件）打包到一个独立的“胖JAR”（Fat JAR）中；二是在运行这个JAR时，正确地为JavaFX应用程序指定其运行时模块路径。
1. 使用Maven Assembly Plugin构建“胖JAR”
maven-assembly-plugin是一个强大的Maven插件，它允许开发者将项目及其所有依赖项（包括传递性依赖）打包成一个独立的、可执行的JAR文件。这确保了在运行时所有必需的类都可用。
立即学习“Java免费学习笔记（深入）”；
在项目的pom.xml文件中，添加以下插件配置：
<build>
<plugins>
<!-- 其他插件配置... -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-assembly-plugin</artifactId>
<version>3.4.2</version> <!-- 使用最新稳定版本 -->
<configuration>
<archive>
<manifest>
<mainClass>mypackage.myproject.Main</mainClass> <!-- 替换为你的主类 -->
</manifest>
</archive>
<descriptorRefs>
<descriptorRef>jar-with-dependencies</descriptorRef>
</descriptorRefs>
</configuration>
<executions>
<execution>
<id>make-assembly</id>
<phase>package</phase> <!-- 绑定到打包阶段 -->
<goals>
<goal>single</goal>
</goals>
</execution>
</executions>
</plugin>
<!-- 确保Maven Compiler Plugin配置正确 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.10.1</version>
<configuration>
<source>19</source> <!-- 替换为你的JDK版本 -->
<target>19</target> <!-- 替换为你的JDK版本 -->
</configuration>
</plugin>
<!-- JavaFX Maven Plugin (可选，主要用于开发和jlink) -->
<plugin>
<groupId>org.openjfx</groupId>
<artifactId>javafx-maven-plugin</artifactId>
<version>0.0.8</version>
<executions>
<execution>
<id>default-cli</id>
<configuration>
<mainClass>mypackage.myproject/mypackage.myproject.Main</mainClass>
<launcher>app</launcher>
<jlinkZipName>app</jlinkZipName>
<jlinkImageName>app</jlinkImageName>
<noManPages>true</noManPages>
<stripDebug>true</stripDebug>
<noHeaderFiles>true</noHeaderFiles>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>配置说明：
-
maven-assembly-plugin:
- <mainClass>: 指定你的JavaFX应用程序的入口类，该类通常继承自javafx.application.Application。
- <descriptorRef>jar-with-dependencies</descriptorRef>: 这是关键，它告诉插件创建一个包含所有项目依赖的JAR文件。
- <phase>package</phase>: 将此插件的执行绑定到Maven的package生命周期阶段，这样在执行mvn clean package时就会自动生成“胖JAR”。
- maven-compiler-plugin: 确保你的项目使用正确的JDK版本进行编译。
- javafx-maven-plugin: 虽然它对于直接生成“胖JAR”不是必需的，但它在开发阶段提供javafx:run等便利功能，并且是使用jlink创建自定义运行时镜像的基础。如果你的目标是生成一个独立的“胖JAR”并手动运行，此插件的配置可能不是最直接的解决方案，但保留它通常无害。
完成配置后，在终端中运行以下Maven命令：
mvn clean package
成功执行后，你会在项目的target目录下找到一个名为 yourproject-SNAPSHOT-jar-with-dependencies.jar 的文件（文件名会根据你的artifactId和version而定）。
2. 正确运行JavaFX可执行JAR
即使你已经创建了一个包含所有依赖的“胖JAR”，但由于JavaFX的模块化特性和其对本地库的依赖，直接使用 java -jar 命令可能仍然不足以启动应用程序。你需要显式地告知JVM JavaFX模块的位置。
运行“胖JAR”的正确命令行格式如下：
java --module-path "C:path oyourjavafx-sdk-19lib" --add-modules javafx.controls,javafx.fxml -jar yourproject-SNAPSHOT-jar-with-dependencies.jar
参数说明：
-
--module-path "C:path oyourjavafx-sdk-19lib":
- 这个参数是强制性的，它告诉JVM在哪里可以找到JavaFX的运行时模块。你需要将其替换为你的JavaFX SDK安装目录下的lib文件夹的绝对路径。例如，如果你下载了JavaFX SDK并解压到 C:Program FilesJavajavafx-sdk-19，那么路径就是 C:Program FilesJavajavafx-sdk-19lib。
- 请注意，即使“胖JAR”包含了JavaFX的类文件，但JavaFX的某些部分（特别是与操作系统交互的本地库）仍然需要从SDK中加载。
-
--add-modules javafx.controls,javafx.fxml:
- 这个参数用于显式地向JVM添加你的应用程序所依赖的JavaFX模块。根据你的module-info.java文件，你可能需要添加更多模块，例如javafx.graphics、javafx.web等。请确保这里列出的模块与你在module-info.java中requires的模块一致。
-
-jar yourproject-SNAPSHOT-jar-with-dependencies.jar:
- 这是指向你通过maven-assembly-plugin生成的“胖JAR”文件的路径。
通过以上两步，你的JavaFX应用程序应该能够成功地从可执行JAR包启动。
注意事项与最佳实践
JDK与JavaFX版本匹配: 确保你使用的JDK版本与pom.xml中org.openjfx依赖的版本兼容。例如，如果你的JDK是19，那么JavaFX版本也应是19系列。
-
module-info.java配置: 仔细检查你的module-info.java文件。确保所有必需的JavaFX模块都已通过requires声明，并且你的应用程序包已通过opens或exports正确暴露给JavaFX运行时。
module mypackage.myproject { requires javafx.controls; requires javafx.fxml; // ... 其他requires ... opens mypackage.myproject to javafx.fxml; // 确保FXML控制器可以访问你的包 exports mypackage.myproject; // 导出你的主包 // ... 其他exports/opens ... } JLink替代方案: 对于更专业的部署场景，javafx-maven-plugin结合jlink工具是更好的选择。jlink可以创建一个自定义的运行时镜像，其中只包含应用程序及其所需的JDK模块和JavaFX模块，形成一个完全独立的、可直接运行的应用程序包，无需单独安装JDK或JavaFX SDK。这会生成一个更大的部署包，但提供了最大的便利性。
路径分隔符: 在Windows系统上，路径使用反斜杠 ，但在命令行中，正斜杠 / 通常也兼容，或者你可以使用双反斜杠 \ 来避免转义问题。在Linux/macOS系统上，使用正斜杠 /。
Manifest文件: 确保maven-assembly-plugin生成的JAR包的META-INF/MANIFEST.MF文件中正确指定了Main-Class。
总结
解决Maven JavaFX项目可执行JAR包的打包和运行问题，核心在于理解JavaFX的模块化特性及其对运行时环境的要求。通过合理配置maven-assembly-plugin来生成包含所有依赖的“胖JAR”，并结合命令行中--module-path和--add-modules参数的正确使用，可以有效避免NoClassDefFoundError等常见错误，确保JavaFX应用程序能够顺利启动和运行。对于追求极致部署体验的开发者，探索jlink工具将是下一步的进阶方向。
