SpringBoot3 + JDK17 + JavaFX21 打包Windows可执行EXE应用程序完整文档

一、文档概述

本文档详细记录基于 SpringBoot3 + JDK17 + JavaFX21 技术栈开发的项目，打包为Windows可执行EXE应用程序的完整流程。最终生成的EXE安装包可在无Java环境的Windows系统独立运行，自动创建桌面/开始菜单快捷方式，仅显示JavaFX图形界面（无冗余控制台弹窗），同时保留SpringBoot对外接口功能。

核心前提 ：操作全程基于Windows系统（Win10/Win11），使用PowerShell执行命令；项目根目录固定为 D:\code\BootFX，所有路径、命令均围绕此目录编写，实际操作时需根据自身环境微调路径（注意事项中会重点说明路径修改要点）。

二、环境准备与依赖说明

2.1 必备环境与路径

依赖项	版本要求	本地路径（示例）	注意事项
JDK	17.x（必须）	D:\software\backend\jdk17	需确保jdk目录下存在jmods文件夹（内含核心模块文件）
JavaFX	21.x（必须，与JDK17兼容）	D:\ok\javafx-jmods-21.0.10	必须下载jmods类型包（非SDK/JAR包），解压后可见javafx.controls.jmod等文件
Maven	3.x+（兼容SpringBoot3）	D:\software\backend\repository（仓库路径）	需配置环境变量，确保PowerShell可直接执行mvn命令

2.2 JavaFX jmods包下载

打开官方下载地址：https://gluonhq.com/products/javafx/
版本选择：21.0.6 或 21.0.10（与示例版本兼容，优先选择匹配版本）
平台选择：Windows（适配本地系统）
下载类型：jmods（重点注意：不可选择SDK或JAR包，否则无法通过jlink生成包含JavaFX的JRE）
下载后解压至本地路径，示例路径为D:\ok\javafx-jmods-21.0.10，解压后需确认目录内无嵌套子目录，直接包含各类jmod文件。

三、完整打包步骤

步骤1：项目打包（生成可执行JAR包）

先通过Maven打包项目，生成SpringBoot+JavaFX可独立运行的JAR包，此步骤是后续所有操作的基础，必须确保JAR包功能正常。

打开PowerShell，进入项目根目录（注意：路径必须准确，否则后续命令会执行失败）：
cd D:\code\BootFX
执行Maven打包命令（跳过测试环节，加速打包，注意：确保项目无编译错误，否则打包会失败）：
mvn clean package -DskipTests
验证JAR包可用性（关键步骤，必须执行 ：此步骤可排查项目本身是否存在功能问题，避免后续打包后无法启动）：
java -jar .\target\BootFX-1.0-SNAPSHOT.jar

✅ 预期结果：JavaFX图形界面正常弹出，SpringBoot后台服务（如Tomcat）启动成功（控制台可看到启动日志），对外接口（如默认8080端口）可正常访问，项目核心功能无异常。

步骤2：生成包含JavaFX的自定义JRE（核心关键步骤）

jpackage默认使用的JRE不包含JavaFX模块，直接打包会导致EXE启动报"模块缺失"错误，因此需通过jlink手动构建包含所有必需模块的轻量JRE（仅保留项目运行所需模块，减小最终EXE体积）。

创建自定义JRE存放目录（注意：目录路径建议与项目根目录同级，避免中文、空格等特殊字符）：
mkdir D:\code\BootFX\custom-jre
执行jlink命令生成自定义JRE（重点注意：--module-path参数中，JDK的jmods路径与JavaFX的jmods路径用分号分隔，不可遗漏任何一个模块；--add-modules参数需包含SpringBoot+JavaFX+Tomcat运行所需的所有核心模块，少模块会导致启动失败）：

jlink --module-path 'D:\software\backend\jdk17\jmods;D:\ok\javafx-jmods-21.0.10'
--add-modules javafx.controls,javafx.fxml,javafx.graphics,javafx.media,javafx.swing,java.base,java.desktop,java.logging,java.sql,java.naming,java.net.http,java.management,java.security.jgss,java.security.sasl,java.xml,java.scripting,java.instrument,java.compiler --output D:\code\BootFX\custom-jre
--strip-debug --no-man-pages
--no-header-files `
--compress=2

✅ 预期结果：D:\code\BootFX\custom-jre目录下生成bin、lib、conf等子文件夹，说明自定义JRE创建成功。

🔍 验证自定义JRE（必须验证 ：确保自定义JRE可正常启动项目，排查模块缺失问题）：
D:\code\BootFX\custom-jre\bin\java.exe -jar D:\code\BootFX\target\BootFX-1.0-SNAPSHOT.jar

✅ 预期结果：与步骤1的验证结果一致，无ClassNotFoundException、NoClassDefFoundError等模块/类缺失错误。

步骤3：创建干净的打包输入目录（避免干扰）

注意：jpackage打包时，若输入目录包含target下的classes、maven-archiver、generated-sources等冗余文件，会导致打包后EXE启动配置错误（如主类找不到），因此需单独创建干净目录，仅放入核心JAR包。

创建干净输入目录：
# 确保目录不存在时自动创建 mkdir -Force D:\code\BootFX\clean-input
仅复制核心JAR包到干净目录（注意：仅复制BootFX-1.0-SNAPSHOT.jar，不要复制其他文件/文件夹）：
copy D:\code\BootFX\target\BootFX-1.0-SNAPSHOT.jar D:\code\BootFX\clean-input\

步骤4：基于自定义JRE打包EXE（最终打包步骤）

通过jpackage命令，结合自定义JRE生成EXE安装包，同时配置桌面/开始菜单快捷方式，隐藏控制台弹窗，适配SpringBoot可执行JAR的特殊启动逻辑。

powershell 复制代码

jpackage `
  --type exe `
  --input D:\code\BootFX\clean-input `
  --name BootFX `
  --main-jar BootFX-1.0-SNAPSHOT.jar `
  --dest D:\code\BootFX\jpackage-output `
  --runtime-image D:\code\BootFX\custom-jre `
  --java-options "-Dfile.encoding=UTF-8" `
  --arguments "-jar","$APPDIR\BootFX-1.0-SNAPSHOT.jar" `
  --win-shortcut `
  --win-menu `
  --win-menu-group "BootFX应用" `
  --install-dir "BootFX"

关键参数说明（含注意事项）

参数	作用	注意事项
--type exe	指定生成Windows系统EXE安装包	仅Windows系统支持此参数，不可用于其他系统
--input	指定打包输入目录（仅含核心JAR包）	必须指向clean-input目录，不可指向target目录
--runtime-image	指定自定义JRE路径	路径必须准确，否则EXE会依赖系统Java环境
--arguments "-jar,..."	强制EXE用-jar方式启动	核心关键：SpringBoot可执行JAR必须用-jar启动，否则会报"找不到主类"错误，$APPDIR为EXE安装后app目录的默认变量，不可修改
--win-shortcut/--win-menu	自动创建桌面/开始菜单快捷方式	无需手动创建，安装后自动生成
无--win-console	隐藏控制台弹窗，仅显示JavaFX界面	如需调试启动日志，可临时添加此参数，调试完成后删除

步骤5：验证EXE安装与启动

卸载旧版本（注意：若之前安装过该应用，必须先卸载，避免安装冲突）：控制面板 → 程序和功能 → 找到"BootFX" → 卸载。
安装新EXE：进入打包输出目录 D:\code\BootFX\jpackage-output，双击 BootFX-1.0.0.exe，按提示完成安装（默认安装路径为C:\Program Files\BootFX）。
启动验证（注意：两种启动方式均需验证，确保快捷方式正常可用）：
- 方式1：双击桌面"BootFX"快捷方式；
- 方式2：点击开始菜单 → 找到"BootFX应用"文件夹 → 点击"BootFX"。

✅ 最终预期结果：仅弹出JavaFX图形界面，无控制台弹窗；SpringBoot后台服务正常启动，对外接口可正常访问；关闭图形界面后，后台服务同步退出，无残留进程。

四、重要注意事项（必看）

路径相关：所有路径（JDK、JavaFX jmods、项目目录、自定义JRE目录）均不可包含中文、空格或特殊字符，否则会导致jlink、jpackage命令执行失败。
模块相关：jlink命令的--add-modules参数不可遗漏模块（尤其是java.instrument、java.compiler），否则会导致SpringBoot/Tomcat启动报类缺失错误；若后续项目新增依赖，需同步新增对应的模块。
JAR包相关：必须确保步骤1生成的JAR包可正常启动，若JAR包本身有问题（如配置错误、依赖缺失），后续打包操作无法修复。
启动逻辑相关：--arguments "-jar,..."参数不可省略，SpringBoot可执行JAR与普通JAR启动逻辑不同，仅支持-jar方式启动，否则必报"找不到主类"错误。
调试相关：若EXE启动失败（无界面、闪退），可临时在jpackage命令中添加--win-console参数，重新打包后启动，通过控制台日志排查问题（常见问题：路径错误、模块缺失、JAR包损坏）。
版本兼容：JDK17需与JavaFX21兼容，SpringBoot3.x需与JDK17兼容，不可混用不兼容版本（如JDK11+JavaFX21、SpringBoot2.x+JDK17）。
干净打包：每次重新打包前，建议删除custom-jre、jpackage-output、clean-input目录，避免旧文件干扰（可通过PowerShell命令强制删除：Remove-Item -Recurse -Force 目录路径）。

五、常见问题排查

问题现象	可能原因	解决方案
jlink命令执行失败，提示"模块不存在"	JavaFX jmods路径错误，或jmods包类型错误（非jmods包）	核对JavaFX jmods路径，重新下载正确的jmods包，确保路径无拼写错误
EXE启动报"找不到或无法加载主类"	未添加--arguments "-jar,..."参数，或参数格式错误	检查jpackage命令，确保--arguments参数正确，格式为"--arguments "-jar","$APPDIR\BootFX-1.0-SNAPSHOT.jar""
EXE启动闪退，无任何界面	自定义JRE缺失核心模块，或工作目录错误	添加--win-console参数重新打包，查看控制台错误日志；核对jlink命令的--add-modules参数，确保模块完整
安装后无桌面/开始菜单快捷方式	jpackage命令遗漏--win-shortcut/--win-menu参数	补充参数重新打包，卸载旧版本后重新安装
启动后中文乱码	缺失-Dfile.encoding=UTF-8参数	确保jpackage命令中包含--java-options "-Dfile.encoding=UTF-8"参数，重新打包

六、总结

本方案的核心是"先验证JAR包可用性→构建包含JavaFX的自定义JRE→干净打包EXE"，关键在于适配SpringBoot可执行JAR的-jar启动逻辑，以及确保自定义JRE模块完整。按文档步骤操作后，可生成无环境依赖、仅显示图形界面、带快捷方式的标准Windows EXE应用程序，满足桌面应用的部署需求。

若实际项目路径、版本与示例不同，需重点核对"环境准备""路径参数""注意事项"三个章节，确保所有配置与自身环境匹配，即可顺利完成打包。

（注：文档部分内容可能由 AI 生成）