解决JavaFX应用程序JAR包运行失败及模块路径配置指南

本教程旨在解决JavaFX应用程序打包成JAR后无法运行的常见问题，特别是遇到“javafx runtime components are missing”错误。文章将详细指导如何下载并配置独立的JavaFX SDK，并通过命令行正确指定–module-path和–add-modules参数来成功启动JavaFX JAR包，确保应用程序在Java 11及更高版本模块化运行时环境下的兼容性与可移植性。

JavaFX JAR包运行失败问题解析

自java 11版本起，oracle jdk不再捆绑javafx运行时组件，将其作为独立模块发布。这意味着，如果您的javafx应用程序是基于java 11或更高版本（如openjdk 17）构建的，并且您将应用程序打包成一个独立的jar文件，那么在尝试通过java -jar yourapp.jar命令运行时，很可能会遇到“javafx runtime components are missing and are required to run this application”的错误。这是因为java虚拟机（jvm）在默认的模块路径中找不到运行javafx应用程序所需的模块。即使尝试将jdk自带的lib目录添加到–module-path也无济于事，因为javafx模块并不在那里。

解决此问题的核心在于为JVM提供JavaFX运行时模块的正确位置。这通常通过下载独立的JavaFX SDK并将其路径明确告知JVM来实现。

解决方案：配置JavaFX SDK并指定模块路径

要成功运行JavaFX应用程序的JAR包，您需要执行以下步骤：

步骤一：下载JavaFX SDK

首先，您需要从官方渠道下载与您所使用的JDK版本兼容的JavaFX SDK。

1. 访问官方下载页面： 前往GluonHQ的JavaFX产品页面：https://www.php.cn/link/f676fd7c5cadc839db8b7e65bfbdd8c6
2. 选择正确的版本： 根据您使用的JDK版本（例如OpenJDK 17），选择相应的JavaFX SDK版本和操作系统平台。通常选择“SDK”包。
3. 解压SDK： 下载完成后，将压缩包解压到一个您方便访问的目录，例如 C:Program FilesJavajavafx-sdk-17 或 C:UsersYourUserJavaFX_SDKjavafx-sdk-17。请记住这个路径，因为稍后会用到。

步骤二：确定JavaFX SDK的lib目录路径

解压后的JavaFX SDK目录中会包含一个lib子目录，其中包含了所有JavaFX模块的JAR文件。您需要获取这个lib目录的完整路径。

立即学习“Java免费学习笔记（深入）”；

示例路径： 如果您的JavaFX SDK解压在 C:UsersAdminJavaFX_SDKjavafx-sdk-17，那么lib目录的路径就是 C:UsersAdminJavaFX_SDKjavafx-sdk-17lib。

步骤三：构建并执行运行命令

有了JavaFX SDK的lib目录路径后，您就可以构建正确的命令行来启动您的JAR包了。

1. 打开命令行工具： 打开命令提示符（windows）或终端（linux/macOS）。

2. 切换到JAR文件所在目录： 使用cd命令切换到您的JavaFX应用程序JAR文件所在的目录。

   

   Pixelcut

   AI产品图片处理——背景移除替换、物体抹除和图片放大

   42

   查看详情

3. 执行命令： 使用以下格式的命令来运行您的JAR文件：

   java --module-path "path/to/javafx-sdk/lib" --add-modules javafx.controls,javafx.fxml -jar YourApp.jar

   参数说明：

   • java: 启动Java虚拟机的命令。
   • –module-path “path/to/javafx-sdk/lib”: 指定JavaFX模块的查找路径。请将”path/to/javafx-sdk/lib”替换为您实际的JavaFX SDK lib目录的路径。
   • –add-modules javafx.controls,javafx.fxml: 指定您的应用程序需要加载的JavaFX模块。javafx.controls通常是必需的，如果您的应用程序使用了FXML，则javafx.fxml也需要添加。根据您的应用程序实际使用的功能，您可能还需要添加其他模块，例如javafx.graphics、javafx.media、javafx.web等。模块之间使用逗号分隔。
   • -jar YourApp.jar: 指定要运行的JavaFX应用程序JAR文件。请将YourApp.jar替换为您实际的JAR文件名。

完整示例： 假设您的JavaFX SDK lib目录在 C:eclipsejdksjavafx-sdk-19lib，您的应用程序JAR文件名为 Rating.jar，并且使用了javafx.controls和javafx.fxml模块，那么运行命令将是：

java --module-path "C:eclipsejdksjavafx-sdk-19lib" --add-modules javafx.controls,javafx.fxml -jar Rating.jar

步骤四（可选）：创建启动脚本

为了方便每次运行，您可以创建一个批处理文件（Windows的.bat文件）或Shell脚本（Linux/macOS的.sh文件）来封装上述命令。

Windows .bat 文件示例 (run.bat)：

@echo off set JAVAFX_SDK_LIB="C:eclipsejdksjavafx-sdk-19lib" set APP_JAR="Rating.jar" set MODULES="javafx.controls,javafx.fxml"  java --module-path %JAVAFX_SDK_LIB% --add-modules %MODULES% -jar %APP_JAR% pause

将此文件保存到与您的JAR文件相同的目录中，双击 run.bat 即可启动应用程序。

注意事项与最佳实践

1. JDK与JavaFX SDK版本匹配： 确保您下载的JavaFX SDK版本与您用于编译和运行应用程序的JDK版本兼容。例如，OpenJDK 17通常应搭配JavaFX SDK 17或更高版本。
2. 模块列表的准确性： –add-modules参数中列出的模块必须是您的应用程序实际使用的。如果遗漏了某个模块，应用程序在运行时可能会抛出新的错误。根据错误日志或应用程序功能逐步添加缺失的模块。
3. ide中的配置： 如果您在IDE（如IntelliJ idea、Eclipse）中开发JavaFX应用程序，也需要类似地配置JavaFX SDK作为项目的依赖项（通常通过maven或gradle）。本教程主要针对JAR包的命令行运行。
4. JLink/JPackage： 对于更专业的部署，Java提供了jlink和jpackage工具。jlink可以将您的应用程序、所需的JDK模块和JavaFX模块打包成一个自包含的运行时镜像，无需用户安装JDK或单独配置JavaFX SDK。jpackage在此基础上更进一步，可以创建平台特定的安装包（如Windows的.exe、macos的.dmg），提供更友好的用户体验。这些是生产环境中部署JavaFX应用程序的推荐方式。

总结

解决JavaFX应用程序JAR包无法运行的问题，关键在于理解Java 11+模块化系统的要求。通过下载独立的JavaFX SDK，并在命令行中正确使用–module-path指定SDK的lib目录，以及使用–add-modules列出应用程序所需的JavaFX模块，您可以确保您的JavaFX应用程序在模块化运行时环境下顺利启动。对于需要频繁运行或分发的应用程序，建议进一步研究jlink和jpackage以实现更便捷的部署。