JavaFX应用程序JAR包运行指南：解决运行时组件缺失问题与模块化配置

本教程旨在解决JavaFX应用程序打包为JAR文件后无法运行，并提示“javafx runtime components are missing”的问题。文章将详细指导用户如何正确下载并配置独立的JavaFX SDK，并通过命令行指定模块路径和所需模块，确保JavaFX应用程序JAR包能够顺利启动。此外，还将提供相关注意事项，帮助开发者更好地理解和处理JavaFX的模块化运行时环境。

在开发javafx应用程序时，开发者常会遇到一个常见问题：应用程序在集成开发环境（ide）中能够正常运行，但当将其打包成可执行jar文件后，却无法启动，并伴随“javafx runtime components are missing and are required to run this application”的错误提示。这通常是由于javafx自jdk 11起不再作为jdk的标准模块捆绑发布，需要单独引入。

问题根源分析

从JDK 11开始，JavaFX被移出标准JDK，成为一个独立的模块。这意味着，如果您的应用程序依赖于JavaFX，仅仅使用java -jar Yourapp.jar命令是不足以启动的，因为Java运行时环境无法自动找到所需的JavaFX模块。尝试将JDK自身的lib目录添加到–module-path是无效的，因为JDK的lib目录不包含JavaFX的运行时组件。

解决方案：配置JavaFX SDK运行时环境

解决此问题的核心在于为Java运行时明确指定JavaFX模块的位置。这需要下载独立的JavaFX SDK，并在运行JAR包时通过命令行参数告知jvm。

1. 下载JavaFX SDK

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

• 访问GluonHQ官方网站：https://www.php.cn/link/f676fd7c5cadc839db8b7e65bfbdd8c6
• 根据您的操作系统和JDK版本（例如，OpenJDK 17），下载对应的JavaFX SDK发行版（通常是sdk版本，而非jmods或src）。
• 将下载的SDK解压到一个易于访问的目录，例如 C:JavaFXjavafx-sdk-xx (其中 xx 是版本号)。解压后，您会看到一个 lib 目录，其中包含了所有JavaFX的运行时JAR文件。

2. 命令行运行JAR包

下载并解压JavaFX SDK后，您可以使用以下命令来运行您的JavaFX应用程序JAR包：

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

java --module-path "C:PathTojavafx-sdk-xxlib" --add-modules javafx.controls,javafx.fxml -jar YourApplication.jar

让我们详细解析这个命令：

Pixelcut

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

42

查看详情

• java: 启动Java虚拟机。
• –module-path “C:PathTojavafx-sdk-xxlib”: 这个参数告诉JVM去哪里寻找模块。您需要将其中的 “C:PathTojavafx-sdk-xxlib” 替换为您实际解压的JavaFX SDK的lib目录路径。请注意，路径中包含空格时需要使用双引号。
• –add-modules javafx.controls,javafx.fxml: 这个参数指定了您的应用程序需要加载哪些JavaFX模块。javafx.controls和javafx.fxml是最常用的两个模块，但您的应用程序可能还使用了其他模块，例如javafx.graphics、javafx.media、javafx.web等。您需要根据您的项目实际依赖来列出所有必需的模块，模块之间用逗号 , 分隔。
• -jar YourApplication.jar: 指定要运行的JavaFX应用程序的JAR文件。

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

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

3. IDE中的配置（开发阶段）

虽然本教程主要关注JAR包的运行，但在开发阶段，您也需要在IDE中正确配置JavaFX SDK，以确保代码能够编译和运行。大多数IDE（如IntelliJ idea、Eclipse）都提供了方便的模块路径或库配置选项，允许您将下载的JavaFX SDK添加到项目的依赖中。

• intellij idea: 通常在项目结构(Project Structure) -> 库(Libraries)中添加JavaFX SDK，并在模块(Modules)的依赖(Dependencies)中勾选。
• Eclipse: 在项目属性(Project Properties) -> Java Build Path -> Libraries 中添加外部JARs，指向JavaFX SDK的lib目录下的所有JAR文件。

正确配置后，IDE会自动在运行/调试时添加相应的VM选项。

注意事项

• JavaFX SDK版本与JDK版本兼容性： 确保您下载的JavaFX SDK版本与您使用的JDK版本兼容。通常，新版本的JavaFX SDK可以与较新的JDK版本（如JDK 11+）一起使用。
• 模块路径的准确性： –module-path参数必须指向JavaFX SDK的lib目录，而不是JDK的lib目录。
• 所有必需模块的列出： –add-modules参数必须包含您的应用程序实际使用的所有JavaFX模块。如果遗漏，可能会在运行时出现NoClassDefFoundError等错误。
• 跨平台分发： 对于需要分发给最终用户的应用程序，仅仅提供一个JAR文件和运行脚本可能不够理想。更专业的做法是使用jlink或jpackage工具创建自包含的运行时镜像或安装包，其中已经包含了所有必需的JavaFX模块和JRE，用户无需额外配置。

总结

解决JavaFX应用程序JAR包无法运行的问题，关键在于理解JavaFX的模块化特性。通过下载独立的JavaFX SDK，并在运行时通过–module-path和–add-modules参数明确指定JavaFX模块的位置，可以确保您的应用程序顺利启动。对于更复杂的部署场景，建议考虑使用jlink或jpackage工具来创建更便捷的自包含应用程序包。掌握这些配置方法，将有助于您更高效地开发和部署JavaFX应用程序。