如果你要做一个Windows桌面小工具又想把程序体积控制在几十兆以内JavaFX这套组合在2024年仍然是非常务实的路线。标题里这几个词放一起IDEA负责开发环境JDK17负责运行时OpenJFX负责UI界面jpackage负责收尾整套链路就是从“写代码”到“交付exe”的一次完整闭环。我见过很多人一提到桌面应用就默认Electron或者直接上Python。Electron确实生态强但动辄一两百兆的安装包、极高的内存占用做一个小型工具实在不划算。而JavaFX配上JDK17再加上OpenJFX的模块化支持不仅启动速度快、界面原生还能利用完整的Java生态最终用官方jpackage工具一条命令打包成exe不依赖外网运行时拷贝到另一台Windows电脑上就能跑。这篇文章我按自己实际操盘的顺序来写先说为什么这么选型再讲环境搭建和项目初始化接着把打包exe的完整流程拆开最后整理几个我踩过的高频坑。无论你是刚接触JavaFX的新手还是之前只用过Swing、想换个UI方案的老开发都应该能从中找到可以直接照抄的步骤。1. 整体设计为什么是IDEA JDK17 OpenJFX这个组合1.1 JavaFX在桌面技术里的真实定位桌面应用开发这件事可选框架很多。Electron用前端技术做跨平台桌面端Tauri用系统WebViewQt走C路线Swing是Java老牌方案。JavaFX并不是最流行的但在“Java开发者做桌面工具”这个场景下它是最省心的。JavaFX的优势很明显UI通过FXML布局文件来写配合CSS调样式界面可以做得比Swing现代很多支持GPU加速复杂界面滚动、动画不至于卡顿本身是纯Java业务逻辑和原生Java生态无缝衔接。比Electron好的地方在于无浏览器内核内存占用和体积都小得多。比Swing好的地方在于UI描述方式更工程化不像写Swing代码那样过度绑定Java代码。OpenJFX这个名字要解释一下JDK11开始Oracle把JavaFX从JDK中拆出来单独发版由开源社区维护也就是OpenJFX。所以你在JDK17里找不到javafx包必须通过Maven或Gradle显式引入。这个变化对开发者来说其实是好事JavaFX库可以独立迭代不会因为JDK版本捆绑而拖后腿。1.2 JDK17为什么是“甜点版本”JDK17是继JDK11之后又一个长期支持版本免费商用而且稳定得很。它不像JDK8那样老旧也不像JDK21那样过于前沿很多第三方库在JDK17上兼容性已经磨得很顺工具链也全部适配。从开发体验上看JDK17把很多实用特性带进了默认环境比如switch表达式、文本块、Records、密封类以及var局部变量推断。写JavaFX事件处理时var加lambda表达式组合起来非常舒服。更重要的是JDK17对模块系统整体表现稳定而JavaFX本身就是按模块设计的这样后续jlink裁剪运行时、jpackage打包exe时能依赖原生的模块化能力比非模块化项目顺畅很多。如果你还在用JDK8做JavaFX我建议尽早迁。JDK8那套老式打包方式在JavaFX上极度痛苦要么外挂一堆jar要么手工配置Class-Path。JDK17 OpenJFX jpackage 才是当前最“官方正统”的桌面应用交付方案。1.3 IDEA在整个开发链路中的作用IDEA在这个组合里承担的不只是写代码的环境。它既负责管理JDK版本又负责Maven依赖解析还可以直接运行JavaFX应用。IDEA社区版就够用了不需要上旗舰版因为JavaFX项目的核心能力由Maven插件和OpenJFX本身提供IDE只是工具而已。我推荐使用Maven来组织项目而不是在IDEA里手动添加jar包。一方面Maven能把JavaFX各模块的依赖关系理清楚另一方面后面的javafx-maven-plugin和jpackage打包都靠Maven的目录约定来工作。IDEA新建项目时选择Maven工程SDK选JDK17剩下的交给IDEA和Maven自动处理。2. 开发环境搭建与项目初始化2.1 JDK17安装和环境变量配置JDK17的安装本身不难难点反而在版本选型和环境变量上。我建议去Adoptium官网下载Eclipse Temurin 17这是OpenJDK的社区构建版免费、无甲骨文账号门槛Windows下的exe安装包也做得很干净。Oracle JDK也可以只是下载时需要登录日常开发社区版完全够用。安装时选择默认路径即可例如C:\Program Files\Eclipse Adoptium\jdk-17.0.9.9-hotspot。装完后务必检查环境变量java -version如果输出类似下面内容说明JDK17已经就绪openjdk version 17.0.9 2023-10-17 OpenJDK Runtime Environment Temurin-17.0.99 (build 17.0.99) OpenJDK 64-Bit Server VM Temurin-17.0.99 (build 17.0.99, mixed mode, sharing)如果你发现命令行还是旧版本多半是因为系统里原来有JDK8或JDK11PATH变量的顺序不对。Windows下建议在系统环境变量里把新装的JDK路径尽量往前排同时检查JAVA_HOME是否指向了正确目录。我见过很多“装了17但项目还是跑在8”的情况基本都是JAVA_HOME残留在旧路径导致的。IDEA里也需要指定SDK。打开File - Project Structure - SDKs点击加号选择JDK定位到安装目录。新建项目时SDK选择17Language level也选17这样IDEA才会用新语法解析代码。2.2 用IDEA创建Maven版JavaFX项目打开IDEA选择New Project左边选Maven右侧Project SDK选17这样生成的是一个标准Maven项目。GroupId可以写com.exampleArtifactId填写项目名比如demo-app。如果你没有特殊需求不需要IDEA自带的JavaFX模板Maven加依赖更可控。项目创建完成后的第一件事是改pom.xml。需要添加两个基础依赖javafx-controls和javafx-fxml。这两个模块负责原生控件和FXML布局解析。为了版本统一我在properties里声明JavaFX版本后面所有依赖都引用同一个版本号。properties maven.compiler.release17/maven.compiler.release javafx.version17.0.9/javafx.version /properties dependencies dependency groupIdorg.openjfx/groupId artifactIdjavafx-controls/artifactId version${javafx.version}/version /dependency dependency groupIdorg.openjfx/groupId artifactIdjavafx-fxml/artifactId version${javafx.version}/version /dependency /dependencies注意JavaFX的版本号最好和JDK17保持一个大版本比如JDK17配JavaFX17不要混用旧版JavaFX。如果你项目里还需要WebView、多媒体等能力就额外加javafx-web、javafx-media但基础工具一般只需要controls和fxml。2.3 编写主类与module-info.javaJavaFX应用的主类必须继承javafx.application.Application。我习惯先写一个极简界面验证环境能跑通再扩展业务逻辑。package com.example.demo; import javafx.application.Application; import javafx.scene.Scene; import javafx.scene.control.Label; import javafx.scene.layout.StackPane; import javafx.stage.Stage; public class MainApp extends Application { Override public void start(Stage stage) { Label label new Label(Hello, JavaFX JDK17!); StackPane root new StackPane(label); Scene scene new Scene(root, 640, 400); stage.setTitle(JavaFX Demo); stage.setScene(scene); stage.show(); } public static void main(String[] args) { launch(args); } }这里Stage相当于窗口Scene是窗口里的内容容器Label是控件。StackPane把控件放在中央是JavaFX里最常用的布局容器之一。同时建议创建module-info.java放在src/main/java根目录。模块化是JavaFX干净的基石虽然不写也能跑但后续jpackage打包时模块信息能让jlink自动分析依赖省掉大量手工配置。module com.example.demo { requires javafx.controls; requires javafx.fxml; exports com.example.demo; }如果你用了FXML就需要把javafx.fxml也requires进来。exports是把自己包里的类导出给外部模块使用jpackage打包时也会根据这个声明来生成启动入口。2.4 第一次运行用Maven插件而不是直接点运行写完主类后你可能会直接点IDEA右上角的绿色运行按钮结果大概率会弹一个报错Error: JavaFX runtime components are missing, and are required to run this application这个报错的原因很简单JavaFX不是JDK内置模块IDEA默认运行方式没有把JavaFX模块添加到模块路径。解决办法有很多但最推荐的是配置javafx-maven-plugin通过Maven运行。在pom.xml末尾加插件build plugins plugin groupIdorg.openjfx/groupId artifactIdjavafx-maven-plugin/artifactId version0.0.8/version configuration mainClasscom.example.demo/com.example.demo.MainApp/mainClass /configuration /plugin /plugins /build然后执行mvn clean javafx:run这个命令会自动设置好模块路径把JavaFX模块挂上然后启动应用。如果你不想敲命令可以在IDEA右侧Maven工具窗口里双击javafx:run效果一样。这里mainClass的写法有讲究斜杠左边是模块名右边是全限定类名。如果你的项目没有module-info.java就要去掉模块名只写com.example.demo.MainApp。我们后面要打包成exe建议直接用模块化的写法。3. 从开发到交付打包exe的完整实操流程3.1 为什么别指望IDEA自带的Artifacts很多从传统Java开发转过来的人第一直觉是File - Project Structure - Artifacts - 新建JAR from modules先把项目打成jar再用exe4j或者Launch4j包一层。这条路在JavaFX项目里基本走不通原因就是JavaFX的本地库和模块信息在普通jar打包流程中很容易丢就算JAR能生成运行也会因为找不到JavaFX模块而崩。在JDK17时代官方推荐的打包路径是jlink jpackage。jlink是JDK自带工具可以根据模块依赖关系裁剪出一套精简的运行时jpackage再基于这套运行时生成平台安装包。整个链条完全支持JavaFX也不需要第三方打包工具。3.2 用jlink裁剪运行时生成精简镜像在使用jpackage之前我们先让Maven插件生成一个jlink镜像。这个镜像本质上是一个只包含必要模块的最小JDK体积通常在40到80兆左右比完整JDK动辄200多兆小很多。在模块化项目下先执行mvn clean javafx:jlink如果没有报错target/jlink目录下会出现bin、conf、lib等目录其中bin目录里有项目的启动脚本。这个脚本可以直接双击运行说明jlink已经自动完成了模块分析和运行时裁剪。如果你希望镜像更小可以手动运行jlink命令设置压缩和日志选项jlink --module-path target/classes;目标JDK所在路径/jmods;OpenJFX的jmods路径 \ --add-modules com.example.demo,javafx.controls,javafx.fxml \ --strip-debug --compress2 --no-header-files --no-man-pages \ --output target/jlink但手动jlink需要指定OpenJFX的jmods路径比较麻烦。用javafx-maven-plugin的好处就是插件自动把OpenJFX的模块路径算好了直接javafx:jlink就能完成。这一步的原理可以简单理解成你告诉jlink“我的应用只需要哪些模块”它就把这些模块和它们依赖的JDK模块集合起来生成一套只够你运行的“小号JDK”。3.3 用jpackage生成exe安装包jlink镜像生成后jpackage就顺理成章了。jpackage也是JDK自带工具它可以把镜像和你的主类入口包成Windows下的安装程序。先试生成一个不带安装界面的app-image这实际上就是单个exe程序加附件的文件夹jpackage --type app-image \ --name DemoApp \ --app-version 1.0.0 \ --vendor YourName \ --runtime-image target/jlink \ --module com.example.demo/com.example.demo.MainApp \ --dest target/dist命令跑完后打开target/dist/DemoApp目录会看到DemoApp.exe。这个exe双击就能运行把整个目录拷贝到其他Windows电脑上也不需要安装JDK。如果你的需求是“一次性发给别人一个绿色版工具”这个方向就够了。如果还想做成标准的安装包exe把--type改成exe即可jpackage --type exe \ --name DemoApp \ --app-version 1.0.0 \ --vendor YourName \ --runtime-image target/jlink \ --module com.example.demo/com.example.demo.MainApp \ --dest target/dist \ --win-menu \ --win-shortcut注意--type exe在Windows下依赖WiX Toolsetjpackage需要调用WiX的编译器来生成安装程序。如果未安装WiX会报错。WiX Toolset是一个开源工具去GitHub下载v3.11版本安装在默认路径再把它bin目录加入系统PATH比如C:\Program Files (x86)\WiX Toolset v3.11\bin。这样jpackage才能找到candle.exe和light.exe。生成好的安装包exe可以直接发给用户双击安装它会自动在开始菜单或桌面创建快捷方式。安装路径默认在用户目录下的AppData不需要管理员权限对环境更友好。3.4 用Maven插件简化重复打包命令行虽然清晰但每次打包都敲一大串容易漏参数。我更习惯把jpackage命令放到脚本里或者直接使用Maven的exec-maven-plugin自动执行。简单场景下写一个package.bat脚本就够了echo off call mvn clean javafx:jlink call jpackage --type exe ^ --name DemoApp ^ --app-version 1.0.0 ^ --vendor YourName ^ --runtime-image target/jlink ^ --module com.example.demo/com.example.demo.MainApp ^ --dest target/dist ^ --win-menu ^ --win-shortcut echo done以后每次要出包双击package.bat就会自动完成从编译到生成安装包的全部过程。如果你和团队有持续集成环境也可以把这两行命令集成到GitLab CI或GitHub Actions的Windows runner里。4. 打包过程中常见问题与排查记录4.1 IDE直接运行报JavaFX运行时缺失这是新手最常遇到的第一道坎。报错信息是JavaFX runtime components are missing。原因在于JavaFX不是JDK自带模块IDEA默认的Run Configuration里没有把它加进模块路径。解决方法有三种选一种即可使用mvn javafx:run运行配置javafx-maven-plugin在IDEA的Run Configuration里添加VM options--module-path和--add-modules指向JavaFX路径使用IDEA插件“JavaFX”自动识别模块。我最推荐第一种因为项目后面的打包流程同样依赖这个插件。如果在IDEA里写代码要频繁调试javafx:run这种方式只是多一步Maven启动实际运行速度也足够快。4.2 打包时提示找不到tools.jar有些老项目或老教程会让你在IDEA里手动引入tools.jar来指导打包但JDK8之后这个文件已经不存在了。如果你用的是JDK17编译或打包时看到cannot determine path to tools.jar library八成是项目里有人配置了一个指向tools.jar的Library或者依赖的老插件在找它。解决办法是彻底清理掉这个Library引用。打开File - Project Structure - Libraries把所有名为tools.jar或包含tools.jar的项删掉然后重新mvn clean。另一个隐蔽来源是Maven仓库里的某些插件包含了tools.jar依赖建议检查一下pom.xml里有没有可疑的依赖尤其是一些老版本的打包插件。4.3 jpackage执行时报找不到WiXjpackage在生成--type exe时需要调用WiX Toolset。报错通常是The jpackage tool requires WiX 3.0 or later to build an EXE installer很多人在这一步卡住以为jpackage出了问题实际上就是少了外部工具。去GitHub搜“wixtoolset”,下载v3.11稳定版安装后把bin目录加到系统PATH然后重新打开命令行跑candle -?确认WiX可用再执行jpackage。如果你只生成app-image则不需要WiX这也是我建议先跑--type app-image验证的原因。4.4 打包后的exe双击没反应如果exe运行起来后完全没有窗口或者闪一下就退出先不要怀疑电脑问题大概率是运行时镜像缺少模块。比如你用了FXML布局但jlink的模块列表里没有包含javafx.fxml又比如用了javafx.controls里的控件却没把该模块加进去。建议用命令行手动运行target/jlink/bin/DemoApp.bat或DemoApp.exe观察控制台有没有输出。因为JavaFX应用通常没有标准输出窗口可以加一段文件日志比如在main方法里写try { launch(args); } catch (Exception e) { java.nio.file.Files.writeString( java.nio.file.Path.of(error.log), java.util.Arrays.toString(e.getStackTrace())); }这样即使界面崩了也能看到错误日志定位原因。最常见的坑是模块声明遗漏exports导致jpackage生成启动入口时找不到主类。4.5 打包后资源文件加载失败JavaFX项目里如果用Image或者FXMLLoader加载资源打包后有时候会找不到文件。这是因为jlink生成的模块化环境中资源不再是简单的classpath路径而是模块内资源路径。比如加载图片时Image img new Image(getClass().getResourceAsStream(/images/logo.png));如果报空指针检查图片是否放在src/main/resources/images/logo.png并且在代码里用getResourceAsStream而不是new File。也可以把需要的资源目录用--input参数传给jpackage让它在应用目录中保留这些资源。这个坑在非模块化项目里不明显但模块化打包后很容易触发提前注意能省不少时间。4.6 安装包体积偏大的处理思路JavaFX应用打包后体积一般在60到100兆之间如果觉得偏大可以从三方面优化使用--strip-debug去掉调试符号使用--compress2启用资源压缩去掉--win-menu和--win-shortcut之外不必要的图标资源。这些选项在javafx:jlink的插件配置里也可以直接配。另外如果一个项目同时依赖多个原生库比如加入javafx-web体积膨胀特别快。我的建议是能用javafx-controls和javafx-fxml就别加web模块JavaFX的WebKit依赖非常重体积直接翻倍。5. 一些实操体会与进阶建议5.1 我的经验模块化是成本最低的选择很多人第一次接触module-info.java会很抗拒觉得多一个文件很麻烦。但JavaFX项目里模块化不是可选项而是“早晚要面对的选项”。如果你一开始就不写模块信息开发阶段确实跑得很顺畅等到了打包环节jlink无法自动生成镜像jpackage也不认识模块入口最后还是得回头补模块声明。与其这样不如新建项目时就写好module-info后面所有工具链都会顺着走。我在实际项目中理想状态是项目结构非常清晰src/main/java放模块声明和Java代码src/main/resources放FXML布局和样式文件module-info.java声明依赖。这样无论是IDEA运行、Maven测试还是jpackage打包都不会出现“开发能跑、打包就死”的问题。5.2 资源加载和缓存路径要提前规划JavaFX应用一旦打包成exe工作目录就不是开发时的项目根目录了容易在文件读写和资源加载上出问题。不要用相对路径写日志或配置文件最好用System.getProperty(user.home)拼接一个应用专属目录比如Path configDir Path.of(System.getProperty(user.home), .demoapp);提前用Files.createDirectories(configDir)保证目录存在。资源文件也统一走classpath不要依赖外部文件。这样你的应用从IDEA运行时和打包后运行时行为一致不会出现那种“本地好好的发给客户就报错”的情况。5.3 适合你扩展的方向如果这个“IDEA JDK17 OpenJFX exe”的链路你已经跑通接下来可以往几个方向扩展用Scene Builder可视化编辑FXML把界面布局和逻辑彻底分离用CSS定义一套统一主题JavaFX和Web样式很接近接入Maven的自动构建脚本做一键打包甚至可以把反编译时的库升级到JavaFX 21但开发环境仍用JDK17因为运行时兼容性已经足够好。我个人的建议是先把这套链路固定成一个项目模板把pom.xml、module-info.java、package.bat都整理好下次开发新工具时直接复制把代码和界面逻辑替换掉就行。JavaFX桌面应用本身并不复杂复杂的是环境配置和交付流程把这两件事做成肌肉记忆你就能把精力全部放在具体业务逻辑上。
IDEA+JDK17+OpenJFX+jpackage：JavaFX桌面应用打包Windows exe全流程
如果你要做一个Windows桌面小工具又想把程序体积控制在几十兆以内JavaFX这套组合在2024年仍然是非常务实的路线。标题里这几个词放一起IDEA负责开发环境JDK17负责运行时OpenJFX负责UI界面jpackage负责收尾整套链路就是从“写代码”到“交付exe”的一次完整闭环。我见过很多人一提到桌面应用就默认Electron或者直接上Python。Electron确实生态强但动辄一两百兆的安装包、极高的内存占用做一个小型工具实在不划算。而JavaFX配上JDK17再加上OpenJFX的模块化支持不仅启动速度快、界面原生还能利用完整的Java生态最终用官方jpackage工具一条命令打包成exe不依赖外网运行时拷贝到另一台Windows电脑上就能跑。这篇文章我按自己实际操盘的顺序来写先说为什么这么选型再讲环境搭建和项目初始化接着把打包exe的完整流程拆开最后整理几个我踩过的高频坑。无论你是刚接触JavaFX的新手还是之前只用过Swing、想换个UI方案的老开发都应该能从中找到可以直接照抄的步骤。1. 整体设计为什么是IDEA JDK17 OpenJFX这个组合1.1 JavaFX在桌面技术里的真实定位桌面应用开发这件事可选框架很多。Electron用前端技术做跨平台桌面端Tauri用系统WebViewQt走C路线Swing是Java老牌方案。JavaFX并不是最流行的但在“Java开发者做桌面工具”这个场景下它是最省心的。JavaFX的优势很明显UI通过FXML布局文件来写配合CSS调样式界面可以做得比Swing现代很多支持GPU加速复杂界面滚动、动画不至于卡顿本身是纯Java业务逻辑和原生Java生态无缝衔接。比Electron好的地方在于无浏览器内核内存占用和体积都小得多。比Swing好的地方在于UI描述方式更工程化不像写Swing代码那样过度绑定Java代码。OpenJFX这个名字要解释一下JDK11开始Oracle把JavaFX从JDK中拆出来单独发版由开源社区维护也就是OpenJFX。所以你在JDK17里找不到javafx包必须通过Maven或Gradle显式引入。这个变化对开发者来说其实是好事JavaFX库可以独立迭代不会因为JDK版本捆绑而拖后腿。1.2 JDK17为什么是“甜点版本”JDK17是继JDK11之后又一个长期支持版本免费商用而且稳定得很。它不像JDK8那样老旧也不像JDK21那样过于前沿很多第三方库在JDK17上兼容性已经磨得很顺工具链也全部适配。从开发体验上看JDK17把很多实用特性带进了默认环境比如switch表达式、文本块、Records、密封类以及var局部变量推断。写JavaFX事件处理时var加lambda表达式组合起来非常舒服。更重要的是JDK17对模块系统整体表现稳定而JavaFX本身就是按模块设计的这样后续jlink裁剪运行时、jpackage打包exe时能依赖原生的模块化能力比非模块化项目顺畅很多。如果你还在用JDK8做JavaFX我建议尽早迁。JDK8那套老式打包方式在JavaFX上极度痛苦要么外挂一堆jar要么手工配置Class-Path。JDK17 OpenJFX jpackage 才是当前最“官方正统”的桌面应用交付方案。1.3 IDEA在整个开发链路中的作用IDEA在这个组合里承担的不只是写代码的环境。它既负责管理JDK版本又负责Maven依赖解析还可以直接运行JavaFX应用。IDEA社区版就够用了不需要上旗舰版因为JavaFX项目的核心能力由Maven插件和OpenJFX本身提供IDE只是工具而已。我推荐使用Maven来组织项目而不是在IDEA里手动添加jar包。一方面Maven能把JavaFX各模块的依赖关系理清楚另一方面后面的javafx-maven-plugin和jpackage打包都靠Maven的目录约定来工作。IDEA新建项目时选择Maven工程SDK选JDK17剩下的交给IDEA和Maven自动处理。2. 开发环境搭建与项目初始化2.1 JDK17安装和环境变量配置JDK17的安装本身不难难点反而在版本选型和环境变量上。我建议去Adoptium官网下载Eclipse Temurin 17这是OpenJDK的社区构建版免费、无甲骨文账号门槛Windows下的exe安装包也做得很干净。Oracle JDK也可以只是下载时需要登录日常开发社区版完全够用。安装时选择默认路径即可例如C:\Program Files\Eclipse Adoptium\jdk-17.0.9.9-hotspot。装完后务必检查环境变量java -version如果输出类似下面内容说明JDK17已经就绪openjdk version 17.0.9 2023-10-17 OpenJDK Runtime Environment Temurin-17.0.99 (build 17.0.99) OpenJDK 64-Bit Server VM Temurin-17.0.99 (build 17.0.99, mixed mode, sharing)如果你发现命令行还是旧版本多半是因为系统里原来有JDK8或JDK11PATH变量的顺序不对。Windows下建议在系统环境变量里把新装的JDK路径尽量往前排同时检查JAVA_HOME是否指向了正确目录。我见过很多“装了17但项目还是跑在8”的情况基本都是JAVA_HOME残留在旧路径导致的。IDEA里也需要指定SDK。打开File - Project Structure - SDKs点击加号选择JDK定位到安装目录。新建项目时SDK选择17Language level也选17这样IDEA才会用新语法解析代码。2.2 用IDEA创建Maven版JavaFX项目打开IDEA选择New Project左边选Maven右侧Project SDK选17这样生成的是一个标准Maven项目。GroupId可以写com.exampleArtifactId填写项目名比如demo-app。如果你没有特殊需求不需要IDEA自带的JavaFX模板Maven加依赖更可控。项目创建完成后的第一件事是改pom.xml。需要添加两个基础依赖javafx-controls和javafx-fxml。这两个模块负责原生控件和FXML布局解析。为了版本统一我在properties里声明JavaFX版本后面所有依赖都引用同一个版本号。properties maven.compiler.release17/maven.compiler.release javafx.version17.0.9/javafx.version /properties dependencies dependency groupIdorg.openjfx/groupId artifactIdjavafx-controls/artifactId version${javafx.version}/version /dependency dependency groupIdorg.openjfx/groupId artifactIdjavafx-fxml/artifactId version${javafx.version}/version /dependency /dependencies注意JavaFX的版本号最好和JDK17保持一个大版本比如JDK17配JavaFX17不要混用旧版JavaFX。如果你项目里还需要WebView、多媒体等能力就额外加javafx-web、javafx-media但基础工具一般只需要controls和fxml。2.3 编写主类与module-info.javaJavaFX应用的主类必须继承javafx.application.Application。我习惯先写一个极简界面验证环境能跑通再扩展业务逻辑。package com.example.demo; import javafx.application.Application; import javafx.scene.Scene; import javafx.scene.control.Label; import javafx.scene.layout.StackPane; import javafx.stage.Stage; public class MainApp extends Application { Override public void start(Stage stage) { Label label new Label(Hello, JavaFX JDK17!); StackPane root new StackPane(label); Scene scene new Scene(root, 640, 400); stage.setTitle(JavaFX Demo); stage.setScene(scene); stage.show(); } public static void main(String[] args) { launch(args); } }这里Stage相当于窗口Scene是窗口里的内容容器Label是控件。StackPane把控件放在中央是JavaFX里最常用的布局容器之一。同时建议创建module-info.java放在src/main/java根目录。模块化是JavaFX干净的基石虽然不写也能跑但后续jpackage打包时模块信息能让jlink自动分析依赖省掉大量手工配置。module com.example.demo { requires javafx.controls; requires javafx.fxml; exports com.example.demo; }如果你用了FXML就需要把javafx.fxml也requires进来。exports是把自己包里的类导出给外部模块使用jpackage打包时也会根据这个声明来生成启动入口。2.4 第一次运行用Maven插件而不是直接点运行写完主类后你可能会直接点IDEA右上角的绿色运行按钮结果大概率会弹一个报错Error: JavaFX runtime components are missing, and are required to run this application这个报错的原因很简单JavaFX不是JDK内置模块IDEA默认运行方式没有把JavaFX模块添加到模块路径。解决办法有很多但最推荐的是配置javafx-maven-plugin通过Maven运行。在pom.xml末尾加插件build plugins plugin groupIdorg.openjfx/groupId artifactIdjavafx-maven-plugin/artifactId version0.0.8/version configuration mainClasscom.example.demo/com.example.demo.MainApp/mainClass /configuration /plugin /plugins /build然后执行mvn clean javafx:run这个命令会自动设置好模块路径把JavaFX模块挂上然后启动应用。如果你不想敲命令可以在IDEA右侧Maven工具窗口里双击javafx:run效果一样。这里mainClass的写法有讲究斜杠左边是模块名右边是全限定类名。如果你的项目没有module-info.java就要去掉模块名只写com.example.demo.MainApp。我们后面要打包成exe建议直接用模块化的写法。3. 从开发到交付打包exe的完整实操流程3.1 为什么别指望IDEA自带的Artifacts很多从传统Java开发转过来的人第一直觉是File - Project Structure - Artifacts - 新建JAR from modules先把项目打成jar再用exe4j或者Launch4j包一层。这条路在JavaFX项目里基本走不通原因就是JavaFX的本地库和模块信息在普通jar打包流程中很容易丢就算JAR能生成运行也会因为找不到JavaFX模块而崩。在JDK17时代官方推荐的打包路径是jlink jpackage。jlink是JDK自带工具可以根据模块依赖关系裁剪出一套精简的运行时jpackage再基于这套运行时生成平台安装包。整个链条完全支持JavaFX也不需要第三方打包工具。3.2 用jlink裁剪运行时生成精简镜像在使用jpackage之前我们先让Maven插件生成一个jlink镜像。这个镜像本质上是一个只包含必要模块的最小JDK体积通常在40到80兆左右比完整JDK动辄200多兆小很多。在模块化项目下先执行mvn clean javafx:jlink如果没有报错target/jlink目录下会出现bin、conf、lib等目录其中bin目录里有项目的启动脚本。这个脚本可以直接双击运行说明jlink已经自动完成了模块分析和运行时裁剪。如果你希望镜像更小可以手动运行jlink命令设置压缩和日志选项jlink --module-path target/classes;目标JDK所在路径/jmods;OpenJFX的jmods路径 \ --add-modules com.example.demo,javafx.controls,javafx.fxml \ --strip-debug --compress2 --no-header-files --no-man-pages \ --output target/jlink但手动jlink需要指定OpenJFX的jmods路径比较麻烦。用javafx-maven-plugin的好处就是插件自动把OpenJFX的模块路径算好了直接javafx:jlink就能完成。这一步的原理可以简单理解成你告诉jlink“我的应用只需要哪些模块”它就把这些模块和它们依赖的JDK模块集合起来生成一套只够你运行的“小号JDK”。3.3 用jpackage生成exe安装包jlink镜像生成后jpackage就顺理成章了。jpackage也是JDK自带工具它可以把镜像和你的主类入口包成Windows下的安装程序。先试生成一个不带安装界面的app-image这实际上就是单个exe程序加附件的文件夹jpackage --type app-image \ --name DemoApp \ --app-version 1.0.0 \ --vendor YourName \ --runtime-image target/jlink \ --module com.example.demo/com.example.demo.MainApp \ --dest target/dist命令跑完后打开target/dist/DemoApp目录会看到DemoApp.exe。这个exe双击就能运行把整个目录拷贝到其他Windows电脑上也不需要安装JDK。如果你的需求是“一次性发给别人一个绿色版工具”这个方向就够了。如果还想做成标准的安装包exe把--type改成exe即可jpackage --type exe \ --name DemoApp \ --app-version 1.0.0 \ --vendor YourName \ --runtime-image target/jlink \ --module com.example.demo/com.example.demo.MainApp \ --dest target/dist \ --win-menu \ --win-shortcut注意--type exe在Windows下依赖WiX Toolsetjpackage需要调用WiX的编译器来生成安装程序。如果未安装WiX会报错。WiX Toolset是一个开源工具去GitHub下载v3.11版本安装在默认路径再把它bin目录加入系统PATH比如C:\Program Files (x86)\WiX Toolset v3.11\bin。这样jpackage才能找到candle.exe和light.exe。生成好的安装包exe可以直接发给用户双击安装它会自动在开始菜单或桌面创建快捷方式。安装路径默认在用户目录下的AppData不需要管理员权限对环境更友好。3.4 用Maven插件简化重复打包命令行虽然清晰但每次打包都敲一大串容易漏参数。我更习惯把jpackage命令放到脚本里或者直接使用Maven的exec-maven-plugin自动执行。简单场景下写一个package.bat脚本就够了echo off call mvn clean javafx:jlink call jpackage --type exe ^ --name DemoApp ^ --app-version 1.0.0 ^ --vendor YourName ^ --runtime-image target/jlink ^ --module com.example.demo/com.example.demo.MainApp ^ --dest target/dist ^ --win-menu ^ --win-shortcut echo done以后每次要出包双击package.bat就会自动完成从编译到生成安装包的全部过程。如果你和团队有持续集成环境也可以把这两行命令集成到GitLab CI或GitHub Actions的Windows runner里。4. 打包过程中常见问题与排查记录4.1 IDE直接运行报JavaFX运行时缺失这是新手最常遇到的第一道坎。报错信息是JavaFX runtime components are missing。原因在于JavaFX不是JDK自带模块IDEA默认的Run Configuration里没有把它加进模块路径。解决方法有三种选一种即可使用mvn javafx:run运行配置javafx-maven-plugin在IDEA的Run Configuration里添加VM options--module-path和--add-modules指向JavaFX路径使用IDEA插件“JavaFX”自动识别模块。我最推荐第一种因为项目后面的打包流程同样依赖这个插件。如果在IDEA里写代码要频繁调试javafx:run这种方式只是多一步Maven启动实际运行速度也足够快。4.2 打包时提示找不到tools.jar有些老项目或老教程会让你在IDEA里手动引入tools.jar来指导打包但JDK8之后这个文件已经不存在了。如果你用的是JDK17编译或打包时看到cannot determine path to tools.jar library八成是项目里有人配置了一个指向tools.jar的Library或者依赖的老插件在找它。解决办法是彻底清理掉这个Library引用。打开File - Project Structure - Libraries把所有名为tools.jar或包含tools.jar的项删掉然后重新mvn clean。另一个隐蔽来源是Maven仓库里的某些插件包含了tools.jar依赖建议检查一下pom.xml里有没有可疑的依赖尤其是一些老版本的打包插件。4.3 jpackage执行时报找不到WiXjpackage在生成--type exe时需要调用WiX Toolset。报错通常是The jpackage tool requires WiX 3.0 or later to build an EXE installer很多人在这一步卡住以为jpackage出了问题实际上就是少了外部工具。去GitHub搜“wixtoolset”,下载v3.11稳定版安装后把bin目录加到系统PATH然后重新打开命令行跑candle -?确认WiX可用再执行jpackage。如果你只生成app-image则不需要WiX这也是我建议先跑--type app-image验证的原因。4.4 打包后的exe双击没反应如果exe运行起来后完全没有窗口或者闪一下就退出先不要怀疑电脑问题大概率是运行时镜像缺少模块。比如你用了FXML布局但jlink的模块列表里没有包含javafx.fxml又比如用了javafx.controls里的控件却没把该模块加进去。建议用命令行手动运行target/jlink/bin/DemoApp.bat或DemoApp.exe观察控制台有没有输出。因为JavaFX应用通常没有标准输出窗口可以加一段文件日志比如在main方法里写try { launch(args); } catch (Exception e) { java.nio.file.Files.writeString( java.nio.file.Path.of(error.log), java.util.Arrays.toString(e.getStackTrace())); }这样即使界面崩了也能看到错误日志定位原因。最常见的坑是模块声明遗漏exports导致jpackage生成启动入口时找不到主类。4.5 打包后资源文件加载失败JavaFX项目里如果用Image或者FXMLLoader加载资源打包后有时候会找不到文件。这是因为jlink生成的模块化环境中资源不再是简单的classpath路径而是模块内资源路径。比如加载图片时Image img new Image(getClass().getResourceAsStream(/images/logo.png));如果报空指针检查图片是否放在src/main/resources/images/logo.png并且在代码里用getResourceAsStream而不是new File。也可以把需要的资源目录用--input参数传给jpackage让它在应用目录中保留这些资源。这个坑在非模块化项目里不明显但模块化打包后很容易触发提前注意能省不少时间。4.6 安装包体积偏大的处理思路JavaFX应用打包后体积一般在60到100兆之间如果觉得偏大可以从三方面优化使用--strip-debug去掉调试符号使用--compress2启用资源压缩去掉--win-menu和--win-shortcut之外不必要的图标资源。这些选项在javafx:jlink的插件配置里也可以直接配。另外如果一个项目同时依赖多个原生库比如加入javafx-web体积膨胀特别快。我的建议是能用javafx-controls和javafx-fxml就别加web模块JavaFX的WebKit依赖非常重体积直接翻倍。5. 一些实操体会与进阶建议5.1 我的经验模块化是成本最低的选择很多人第一次接触module-info.java会很抗拒觉得多一个文件很麻烦。但JavaFX项目里模块化不是可选项而是“早晚要面对的选项”。如果你一开始就不写模块信息开发阶段确实跑得很顺畅等到了打包环节jlink无法自动生成镜像jpackage也不认识模块入口最后还是得回头补模块声明。与其这样不如新建项目时就写好module-info后面所有工具链都会顺着走。我在实际项目中理想状态是项目结构非常清晰src/main/java放模块声明和Java代码src/main/resources放FXML布局和样式文件module-info.java声明依赖。这样无论是IDEA运行、Maven测试还是jpackage打包都不会出现“开发能跑、打包就死”的问题。5.2 资源加载和缓存路径要提前规划JavaFX应用一旦打包成exe工作目录就不是开发时的项目根目录了容易在文件读写和资源加载上出问题。不要用相对路径写日志或配置文件最好用System.getProperty(user.home)拼接一个应用专属目录比如Path configDir Path.of(System.getProperty(user.home), .demoapp);提前用Files.createDirectories(configDir)保证目录存在。资源文件也统一走classpath不要依赖外部文件。这样你的应用从IDEA运行时和打包后运行时行为一致不会出现那种“本地好好的发给客户就报错”的情况。5.3 适合你扩展的方向如果这个“IDEA JDK17 OpenJFX exe”的链路你已经跑通接下来可以往几个方向扩展用Scene Builder可视化编辑FXML把界面布局和逻辑彻底分离用CSS定义一套统一主题JavaFX和Web样式很接近接入Maven的自动构建脚本做一键打包甚至可以把反编译时的库升级到JavaFX 21但开发环境仍用JDK17因为运行时兼容性已经足够好。我个人的建议是先把这套链路固定成一个项目模板把pom.xml、module-info.java、package.bat都整理好下次开发新工具时直接复制把代码和界面逻辑替换掉就行。JavaFX桌面应用本身并不复杂复杂的是环境配置和交付流程把这两件事做成肌肉记忆你就能把精力全部放在具体业务逻辑上。
