Gradle 构建 JavaFX 完整教程：OpenJFX Samples 中 javafxplugin 与 jlink 插件实战

Gradle 构建 JavaFX 完整教程：OpenJFX Samples 中 javafxplugin 与 jlink 插件实战

【免费下载链接】samplesJavaFX samples to run with different options and build tools项目地址: https://gitcode.com/gh_mirrors/samples5/samples

对于刚接触 JavaFX 的开发者来说，Gradle 构建 JavaFX项目时最头疼的莫过于环境配置：依赖下载、模块路径、打包分发，每一步都可能踩坑。好消息是，OpenJFX Samples 官方示例仓库（JavaFX samples to run with different options and build tools）提供了一套开箱即用的参考工程，手把手演示了如何用javafxplugin与jlink插件完成 JavaFX 的构建、运行与打包。本文将以这些真实示例为主线，带你快速掌握 Gradle 构建 JavaFX 的完整流程。

为什么用 Gradle 构建 JavaFX：三大优势

在正式动手前，先明确一个核心问题：为什么社区推荐用 Gradle 而不是纯命令行来构建 JavaFX？

• 依赖自动管理：JavaFX 各模块（controls、fxml、graphics 等）通过javafxplugin插件自动引入，无需手动拼 classpath。
• 一键运行：./gradlew run即可启动桌面应用，适合新手快速验证。
• 原生打包：配合jlink插件，可生成免 JDK 的定制运行时与可执行文件，方便分发给普通用户。

OpenJFX Samples 正好覆盖了这三种场景，示例均可在 README.md 中找到对应说明。

环境准备：克隆项目与 JDK 配置

Gradle 构建 JavaFX 需要 JDK 11 及以上版本（示例中 JavaFX 版本为 21，建议 JDK 17+）。先克隆官方示例仓库：

git clone https://gitcode.com/gh_mirrors/samples5/samples

仓库内的 Gradle 示例按使用场景分为三类，你可以按需选择：

javafxplugin 插件核心配置：三步搞定依赖

org.openjfx.javafxplugin插件是整个 JavaFX 构建体系的地基。以最简示例 HelloFX/Gradle/hellofx/build.gradle 为例，配置仅需三步：

plugins { id 'application' id 'org.openjfx.javafxplugin' version '0.1.0' } javafx { version = "21" modules = [ 'javafx.controls' ] } mainClassName = 'HelloFX'

要点解读：

• plugins块声明插件版本，0.1.0是官方推荐的稳定版；
• javafx块指定JavaFX 版本号与所需模块列表，按需引入javafx.controls、javafx.fxml等；
• mainClassName指向入口类，./gradlew run即可启动窗口。

需要 FXML 界面时，只需把 modules 改为['javafx.controls', 'javafx.fxml']，参见 IDE/VSCode/Modular/Gradle/hellofx/build.gradle。

模块化 vs 非模块化：两种 Gradle 工程怎么选

OpenJFX Samples 同时提供了模块化（Modular）与非模块化（Non-modular）两种工程，区别如下：

模块化工程在application块中多一行mainModule声明（见 CommandLine/Modular/Gradle/hellofx/build.gradle）；非模块化工程则通过jar块将运行依赖打入 fat jar，Manifest 指向Launcher类（见 CommandLine/Non-modular/Gradle/hellofx/build.gradle）。

jlink 插件实战：一键生成 JavaFX 自定义运行时

这是本教程的重头戏。org.beryx.jlink插件（版本 2.26.0）可以把模块化 JavaFX 应用连同精简后的 JRE 一起打包，产出无需安装 JDK 的可执行程序。核心配置如下：

jlink { options = ['--strip-debug', '--compress', '2', '--no-header-files', '--no-man-pages'] launcher { name = 'hellofx' } }

• options用于瘦身：去掉调试信息、启用压缩，让产物更小；
• launcher.name指定生成的可执行文件名；
• 配置位于 CommandLine/Modular/Gradle/hellofx/build.gradle 完整示例中。

执行构建并运行：

cd CommandLine/Modular/Gradle/hellofx ./gradlew jlink build/image/bin/hellofx

Windows 用户运行build\image\bin\hellofx.bat即可。产物目录build/image/bin下就是可独立分发的完整应用。

在 VSCode 中快速运行 Gradle JavaFX 任务

如果不想敲命令，VSCode 配合 Java 与 Gradle 扩展（Extension Pack for Java、Gradle for Java）可直接在图形界面操作。打开hellofx文件夹后，在 Gradle Projects 面板展开Tasks > application，点击run任务即可启动应用：

非模块化工程的操作完全相同，只是入口类为MainApp：

需要生成自定义运行时，则在Tasks > build分组中运行jlink任务。首次构建 Gradle 会自动下载 wrapper（示例锁定 Gradle 8.5，见gradle/wrapper/gradle-wrapper.properties），耐心等待即可。

常见问题与最佳实践

最后整理几个高频坑，帮你少走弯路：

1. JAVA_HOME 未指向 JDK：在 IDE/VSCode/Modular/Gradle/hellofx/gradle.properties 中取消注释并设置org.gradle.java.home。
2. 非模块化工程 jlink 报错：jlink 要求模块化工程，非模块化请改用 fat jar 或增加模块化改造。
3. 跨平台分发：非模块化工程中可通过runtimeOnly声明javafx-graphics的 win/linux/mac 平台坐标，一次构建多平台 jar。
4. 版本一致性：JavaFX 版本与 JDK 保持兼容，示例统一使用 JavaFX 21，建议搭配 JDK 17 以上使用。

通过本文的实战，你已经掌握了 Gradle 构建 JavaFX 的核心链路：javafxplugin 配置依赖、模块化选择、jlink 打包分发，以及 IDE 中的图形化操作。下一步，不妨基于 OpenJFX Samples 中的其他示例（Maven、命令行、Eclipse 等），对比不同构建方式的差异，选择最适合自己项目的方案。

【免费下载链接】samplesJavaFX samples to run with different options and build tools项目地址: https://gitcode.com/gh_mirrors/samples5/samples