上周帮某内部运维团队把一个小型数据看板服务从java -jar的绿色版方案，改成了双击安装、自动带快捷方式的独立安装包。整个过程用的主要是 JDK 自带的 jpackage 工具，Spring Boot 项目本身几乎没改代码，只是调整了打包脚本和部分启动参数的传递方式。
这件事本身有不少资料讲过，但实际做的时候还是踩了几个文档不会直接告诉你的坑。比如启动器闪退、工作目录变化导致配置文件读不到、Linux 打包时缺少工具链、 Windows 打 MSI 时对安装器的依赖等等。如果你也想把 Spring Boot 应用交付给不懂命令行的同事，或者希望产品在客户面前更像一个正经软件，这篇文章应该能帮你少走不少弯路。
1. 为什么要把 Spring Boot 做成独立安装包
1.1 一个真实的分发场景
很多 Spring Boot 项目的交付方式其实就是一条命令：把项目打成可执行 Jar，丢给部署的人，让对方java -jar app.jar。这套流程在研发环境里完全没问题，但一旦目标使用者是业务部门、运维值班、客户现场的 IT 人员，麻烦就来了。
我当时遇到的场景是：某团队需要一个内部数据看板，后端是 Spring Boot，前端静态资源打包在一个 Jar 里。应用部署到几台 Windows 办公电脑上，使用者只希望桌面有个图标，双击之后浏览器自动打开看板页面。他们不会开命令行，也不愿意去配置 Java 环境，更不关心进程是怎么拉起来的。
如果直接把一个 Jar 发给对方，意味着我需要先确保每台机器都装了匹配的 JDK，还要帮他们配环境变量，甚至可能要写一个启动脚本。这确实能做，但每台机器手动操作一次，等着你的就是无尽的环境问题。
安装包方案就不一样了。它至少能解决三件事：把 JRE 或 JDK 运行时一起带给用户，不再依赖目标机器预装 Java；提供一个标准的安装、卸载入口；自动创建桌面快捷方式、开始菜单目录和文件关联。这些能力对于内部工具来说未必算刚需，但在客户现场、外出演示、标准化交付这些场景里，价值非常明显。
1.2 可执行 Jar 方案的四个痛点
我并不是说绿色版 Jar 一无是处，它在服务器部署和容器化场景里仍然是最合适的选择。但如果你想把它作为最终交付物发给非技术用户，通常要面对这几个问题。
第一，JDK 版本和指令集不匹配。目标机器上有 Java，但版本比编译时低，或者 32 位、64 位匹配不上，java -jar会直接失败。你在自己电脑上运行正常，换台机器就歇菜，这个现象在混用办公设备的环境里太常见了。
第二，命令行启动门槛高。双击 Jar 在很多 Windows 机器上默认不会执行，只会打开压缩软件列表。即使有启动脚本，用户也可能把脚本路径搞错，或者误改脚本导致路径失效。未受过训练的用户对命令行天然有距离感，任何需要手动输入的命令都是隐患。
第三，缺少卸载和版本管理。绿色版目录删不干净、旧版本覆盖新版本时可能残留，升级只能靠手动覆盖文件。如果应用在运行，Windows 还会锁定 Jar 文件，直接覆盖会失败，真正搞起来用户根本不知道该怎么办。
第四，使用体验不像一个“产品”。没有应用图标、没有安装路径定义、没有版本号显示、没有启动 Do 文件关联。对客户来说，这看起来就是一个临时脚本，而不是可以正式使用的工具。
jpackage 不是唯一能解决这些问题的方案，但它是最接近“开箱可用”的路线：工具内置于 JDK，不引入额外的授权成本，也不需要第三方的商业安装包制作工具。
2. jpackage 到底是怎么工作的
2.1 它支持哪些安装包格式
jpackage 是 JDK 官方提供的打包工具，从 JDK 14 开始孵化，JDK 16 正式成为标准工具。它能根据当前操作系统，把 Java 应用打包成对应平台的原生安装格式。
| 平台 | 安装包格式 | 说明 |
|---|---|---|
| Windows | MSI、EXE | MSI 适合企业批量分发，EXE 安装体验更友好，都支持静默安装参数 |
| Linux | DEB、RPM | 分别对应 Debian 系和 RedHat 系的发行版 |
| macOS | DMG、PKG | DMG 是常见的拖拽安装镜像，PKG 适合需要安装向导的场景 |
除了这些安装包格式，jpackage 还支持app-image，也就是不生成安装器，只生成一个解压后就能运行的应用目录。这个格式太重要了，后面我会专门讲。
有一点需要特别注意：jpackage 不支持交叉打包。在 Windows 上运行 jpackage 只能产出 Windows 安装包，在 Linux 上只能产出 Linux 安装包，在 macOS 上只能产出 macOS 安装包。如果你需要同时交付三个平台，必须准备三条构建链路，或者使用各自平台的 CI 执行器并行跑。
2.2 从 Jar 到安装包的内部流程
jpackage 的整个工作流程大致可以分成三个阶段。
第一阶段是解析启动参数。它会读取你提供的输入目录、主 Jar、主类、应用名称、图标、JVM 参数等信息，构建出一个应用配置描述。这个阶段也是出错率最高的地方，尤其是在 Spring Boot 场景下，主类不是业务类，而是启动器类，如果这一阶段配置错了，后面的所有操作都是在浪费时间。
第二阶段是生成应用镜像，也就是app-image。jpackage 会把目标应用的 Jar 放到镜像的 app 目录下，再把 JDK 运行时复制到镜像的 runtime 目录中，最后生成一个平台原生的启动器。这个启动器本质上是一个可执行程序，内部会调用java启动逻辑，把 JVM 跑起来并加载你的主类。app-image 在 Windows 下对应一个带.exe的目录，在 Linux 下是一个包含可执行文件的目录，在 macOS 下是一个.app包。
第三阶段是封装成安装包。如果指定了--type msi或--type exe，jpackage 会调用系统上的安装包制作工具，把 app-image 再包装成安装器。Windows 下生成 MSI 和 EXE 时通常依赖 WiX Toolset 这类开源工具；Linux 下生成 DEB 依赖dpkg相关工具，RPM 依赖rpmbuild；macOS 的 DMG 和 PKG 则有系统自带工具支持。
这个过程可以手动拆开来看：先做 app-image，再手动验证运行，最后再打成安装包。这样做的好处是，一旦安装包有问题，你能立刻知道到底是应用本身启动失败，还是封装阶段出了问题。
2.3 为什么 Spring Boot 的可执行 Jar 能直接配合
Spring Boot 默认打出来的可执行 Jar 和普通 Jar 有一个很大的区别：真正的业务代码不在根目录，而是被放在BOOT-INF/classes目录下，依赖库则被放在BOOT-INF/lib目录下。启动时，Spring Boot 通过自定义类加载器读取这些内部结构，而不是简单依靠 JVM 的 classpath 机制。
这就意味着，想让 Spring Boot 应用通过 jpackage 启动，你不能把业务类的主类直接传给 jpackage，而是要设置成org.springframework.boot.loader.JarLauncher。JarLauncher 是 Spring Boot 提供的启动器，它负责创建自定义类加载器、定位嵌套 Jar 并加载真正的应用启动类。
jpackage 干的事情其实很朴素：启动一个 JVM，设置好 classpath，然后调用指定主类。至于主类内部怎么加载资源、怎么管理嵌套 Jar，那是 Spring Boot 自己的逻辑。所以你只需要让 jpackage 去调用 JarLauncher，剩下的事情 Spring Boot 会自动完成。
很多人在这一步卡住，是因为把 jpackage 的主类参数写成了自己的Application类，结果启动时 JVM 只能看到外层的 JarLauncher 类路径，找不到BOOT-INF/classes里的业务类，直接报ClassNotFoundException。我建议在打包脚本里显式写清楚主类是 JarLauncher，不要依赖 jpackage 自动推断，省得换版本或换机器时突然失效。
3. 打包前的工程准备与配置检查清单
3.1 版本搭配是第一个关键决策
jpackage 本身要求 JDK 16 以上，如果你还在用 JDK 8 或 JDK 11，那就没办法直接用。Spring Boot 2.7.x 支持 JDK 8 到 JDK 20，Spring Boot 3.x 要求 JDK 17 起。
我在这个项目里用的是 JDK 17 加 Spring Boot 2.7.14。选择 JDK 17 的主要原因是它是 LTS 版本，jpackage 从 17 开始已经足够稳定；Spring Boot 2.7 又正好在维护周期内，兼容性上比较保守，不会因为版本太新遇到一堆新特性问题。
如果你准备用 Spring Boot 3.x，那 JDK 至少得是 17，这个组合没问题，但要提醒一点：Spring Boot 3 默认使用 Jakarta EE 命名空间，部分旧依赖如果还在用javax包，打包后会直接启动失败。这类兼容性问题不是 jpackage 的锅，却会在安装包里集中暴雷，因为安装包环境比开发环境更接近“干净机器”，各种缺依赖的问题藏不住。
3.2 检查可执行 Jar 的 Main-Class
在开始打安装包之前，我强烈建议你先确认一下项目打出来的 Jar 是标准 Spring Boot 可执行 Jar。检查方法很简单，直接在命令行里查看 Jar 包内的META-INF/MANIFEST.MF。
jar xf demo-data-board.jar META-INF/MANIFEST.MF cat META-INF/MANIFEST.MF正常情况下，Main-Class应该是org.springframework.boot.loader.JarLauncher，然后旁边还有一行Start-Class，那才是你项目里的业务主类。这两个字段的区别很容易被忽略，记住一句话：jpackage 关心Main-Class，Spring Boot 关心Start-Class。
如果你发现Main-Class指向的不是 JarLauncher，而是直接改成业务主类，那就说明项目的 spring-boot-maven-plugin 可能没有正确执行 repackage，或者打包方式被覆盖了。这时候先去检查 pom.xml，确认 spring-boot-maven-plugin 的repackage目标已经绑定到 package 阶段。
<plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> <executions> <execution> <goals> <goal>repackage</goal> </goals> </execution> </executions> </plugin>3.3 提前备好图标、版本号和供应商信息
安装包看起来“正经不正经”，图标和元信息的作用很大。jpackage 里和图标相关的参数有平台差异：Windows 用.ico，Linux 用.png，macOS 用.icns。你需要准备对应格式的图标文件，打包时用--icon指定。
版本号、应用名称、供应商、版权这些信息通过--app-version、--name、--vendor、--copyright传进去，会显示在安装向导、程序卸载列表、文件属性等位置。这个细节对内部工具来说可能无所谓，但如果应用要拿给外部客户看，这些字段直接决定了专业度。
还建议顺手写一个构建脚本，比如build-package.sh，把这些参数固化下来。不要每次打包都手敲命令，因为你迟早会忘记某个参数，然后花一下午找原因。
4. 一个数据看板应用从 Jar 到安装包的完整实操
4.1 第一步：先用 app-image 验证运行
我不是一上来就打 MSI，而是先打一个 app-image 目录。这个目录其实就是安装包解压后的结果，相当于把运行环境完整地暴露在你面前。任何启动问题，在 app-image 阶段暴露得最直接，排查也最方便。
jpackage \ --type app-image \ --name DataBoard \ --app-version 1.0.0 \ --vendor "某内部团队" \ --input target \ --main-jar demo-data-board.jar \ --main-class org.springframework.boot.loader.JarLauncher \ --dest dist这条命令会把target目录下的 Jar 取出来，生成dist/DataBoard/。Windows 下里面会有一个DataBoard.exe，Linux 下是一个可执行文件，macOS 下是.app目录。全局搜索一下dist/DataBoard下有没有启动器文件，然后直接双击运行。
我在这里遇到过一件很有意思的事：如果直接把dist/DataBoard/DataBoard.exe双击运行，应用能正常启动，但旁边的runtime目录却不会自动出现在系统 PATH 里。jpackage 生成的启动器并不依赖 PATH 环境变量，它会通过相对路径找到自身所在的 runtime 目录，所以这个不用担心。
确认 app-image 能启动后，再做下一步。如果在 app-image 阶段就启动失败，请直接看第 5 节的排查思路，不要在安装包封装阶段浪费时间。
4.2 Windows 平台：把 app-image 包装成 MSI
确认 app-image 跑通之后，Windows 下生成 MSI 的命令和前面非常相似，只需要把--type改成msi，再加上一些 Windows 特有的参数。
jpackage \ --type msi \ --name DataBoard \ --app-version 1.0.0 \ --vendor "某内部团队" \ --input target \ --main-jar demo-data-board.jar \ --main-class org.springframework.boot.loader.JarLauncher \ --win-shortcut \ --win-menu \ --win-menu-group "DataBoard Tools" \ --license-file license.txt \ --dest dist--win-shortcut会在桌面创建快捷方式，--win-menu会把应用目录放到开始菜单里。如果你需要生成 EXE 安装程序，把--type改成exe即可。
但要注意，Windows 下生成 MSI 或 EXE 时，jpackage 还需要额外的安装器工具支持，最常见的是 WiX Toolset。如果缺少这个工具，终端会报类似“The jpackage tool requires certain tools and libraries to be present”的错误。解决办法是去官网下载合适的版本安装，并把安装目录加入 PATH，然后重新打开终端再跑 jpackage。
我当初第一次打 MSI 就卡在这个环境依赖问题上，因为完全没意识到 jpackage 不是全自包含的。后来把 WiX 装好之后，MSI 一分钟左右就能出来。
4.3 Linux 平台：DEB 与 RPM 的差异化处理
Linux 平台的打包思路是一样的，但命令参数有一定差异。Debian 系要用 DEB，RedHat 系要用 RPM，jpackage 分别通过--type deb和--type rpm来指定。
jpackage \ --type deb \ --name databoard \ --app-version 1.0.0 \ --vendor "某内部团队" \ --input target \ --main-jar demo-data-board.jar \ --main-class org.springframework.boot.loader.JarLauncher \ --linux-shortcut \ --linux-menu-group "Development" \ --dest distLinux 的打包机需要确保有对应的打包工具链：生成 DEB 需要dpkg-deb，生成 RPM 需要rpmbuild及相关开发包。不同发行版的工具名略有差异，可以先在打包机上执行which dpkg-deb或which rpmbuild检查。
还有一个 Linux 特有的坑：如果你在服务器上安装这个 DEB 包，jpackage 默认会把应用装到/opt/databoard这样的目录下，快捷方式的.desktop文件里写的 Exec 路径会指向这个目录。如果你的应用有自定义配置，放在/etc/下会更符合 Linux 用户习惯，但 jpackage 默认不会帮你处理配置文件的迁移，这部分需要应用自己在启动时去读取外部目录。
4.4 macOS 平台：DMG 与应用签名
macOS 平台的流程同理，但多了一个不能跳过的环节：应用签名。如果你不打任何签名，构建出来的 DMG 或 PKG 在分发到其他 Mac 上时，大概率会被 Gatekeeper 拦截，用户需要手动去系统设置里允许运行。
jpackage \ --type dmg \ --name DataBoard \ --app-version 1.0.0 \ --vendor "某内部团队" \ --input target \ --main-jar demo-data-board.jar \ --main-class org.springframework.boot.loader.JarLauncher \ --mac-sign \ --mac-signing-key-user-name "Developer ID Application: ..." \ --dest dist如果只是在团队内部使用，没有开发者证书，也可以不签名，但分发路径会麻烦一点：用户首次打开时可能看到“验证开发者”的警告，或者需要右键打开并确认。我的建议是，内部工具至少做一个本地签名，或者准备一份简单的使用说明，告诉用户遇到拦截时怎么放行。
5. 安装后最容易踩的坑：现象、原因、排查思路
5.1 启动器闪退：闪退背后的日志去哪了
app-image 阶段最常见的现象是：双击.exe后，窗口一闪而过，什么都没留下。这时候最难的问题是看不到日志，因为 Spring Boot 的日志默认输出到控制台，启动器一闪就没，你根本来不及看。
解决办法有两个方向。一是先不用 jpackage 启动，直接手动执行 app-image 里对应的命令行，把启动器拆开来看它到底调用了什么。Windows 下最简单的方式是打开终端，切到 app-image 目录，执行启动器同路径下的runtime/bin/java.exe，手动带上一串参数运行主类。二是给 jpackage 传--java-options，比如：
jpackage \ --type app-image \ --name DataBoard \ --input target \ --main-jar demo-data-board.jar \ --main-class org.springframework.boot.loader.JarLauncher \ --java-options "-Dlogging.level.root=INFO" \ --java-options "-Dconsole.log=true" \ --dest dist如果你用的是 Logback 或 Log4j2，可以提前配置好文件输出，让 Spring Boot 启动时同时写文件日志。这样就算启动器闪退，你也能去安装目录的 logs 文件夹看到详细信息。
闪退最常见的原因是主类指定错误。很多教程里都强调过要写org.springframework.boot.loader.JarLauncher，但实际执行时很容易手滑写成自己的业务类。如果Main-Class指向业务类，JVM 会直接告诉你找不到BOOT-INF/classes里的类，一瞬间就退出。
第二种常见原因是启动时某个外部依赖无法加载。比如数据库驱动、消息队列客户端、本地化依赖等，在开发环境有，但在打包机的~/.m2里没有完整拉取。这种情况在开发环境看不出来，在干净的安装包环境才会暴露。
5.2 工作目录不是你以为的那个目录
这是一个非常隐蔽的问题。Spring Boot 应用如果用了相对路径去读取外部配置文件，在 IDEA 里运行没问题，但通过 jpackage 生成的快捷方式启动时，当前工作目录很可能不是你预期的地方。
Windows 双击桌面快捷方式时，工作目录取决于快捷方式里设置的“起始位置”。如果你没有显式设置，可能是启动器所在目录，也可能是C:\Windows\System32。Linux 从桌面启动时，.desktop 文件里的Path字段也有同样的问题。
我在开发这个看板应用时，配置文件就放在 Jar 同级的config/目录下，开发环境用相对路径读得好好的，打成安装包以后同一个写法直接拿不到文件。最后排查发现，应用的工作目录根本不是安装目录，相对路径自然失效。
更稳妥的做法是在应用代码里不要依赖相对路径。外部配置文件统一放到用户目录或者系统级配置目录，比如 Windows 用AppData，Linux 用$HOME/.config，macOS 用~/Library/Application Support。然后通过System.getProperty("user.home")去拼路径。
如果你确实需要支持安装目录下的config/，那就要在启动参数里显式指定-Dspring.config.location，并且把路径写死，或者通过启动脚本把工作目录切到安装目录。jpackage 没有“安装目录”这种运行时变量给你直接用，所以这并不是一个特别顺滑的方案。
5.3 外置配置文件和升级时的残留问题
安装包方案天然会让用户觉得“所有东西都在安装目录里”，但对 Windows 来说，安装目录通常在Program Files下，普通用户没有写权限。如果你把application.yml放在安装目录下，用户想修改数据库地址都无从下手。
比较好的做法是把配置分成两层：Jar 内置一份默认配置，再通过外部配置目录读取可覆盖项。外部配置目录放在上面说的用户配置目录里。这样做既保证了应用开箱能跑，又允许高级用户按需修改。
升级时也有一个容易踩的坑：如果旧版本正在运行，新版本的安装包尝试覆盖安装目录里的 Jar 文件，Windows 会因为文件被占用而失败，或者要求用户先关闭应用。你需要在安装包层面处理这种情况，比如在打包脚本里加入检测进程的逻辑，或者在部署文档里明确告诉用户“升级前先退出旧版本”。这种问题在 CI 自动升级场景里尤其麻烦，值得提前规划。
6. 体积优化：用 jlink 裁剪运行时到底值不值
6.1 不裁剪时，安装包体积有多大
很多人第一次打完安装包，会被体积吓一跳。一个只有几十 MB 的 Spring Boot Jar，打出来的安装包很可能超过 150 MB。多出来的部分主要是捆绑的 JDK 运行时，jpackage 默认会把当前 JDK 的大多数模块复制进去。
这不是 bug，而是 jpackage 的设计思路：目标是让目标机器不依赖任何额外运行时，那自然要带一个完整的 JRE。但你说一个只有基础 Web 功能的数据看板，真的需要java.desktop、jdk.javadoc、java.compiler这些模块吗？其实不需要。
裁剪运行时的思路是用 jlink 生成一个精简的运行时镜像，再把这个镜像交给 jpackage 使用。裁剪得好，安装包体积能从 150 MB 降到 80 MB 甚至更低。但代价是你要对应用的依赖模块有清晰的认知，否则容易出现启动时发现缺模块的尴尬。
6.2 裁剪运行时的保守操作流程
第一步，用jdeps分析 Jar 的模块依赖。jdeps 是 JDK 自带工具，可以扫描类文件里引用的包并映射到 Java 模块。
jdeps --ignore-missing-deps --print-module-deps --recursive demo-data-board.jar把输出结果拿来作为 jlink 的--add-modules参数。但这里有个大前提：jdeps 只能分析类之间的直接字节码引用，如果应用用了反射、动态代理、SPI 机制，jdeps 会漏报。Spring Boot 的自动配置大量使用META-INF/spring.factories和反射，所以 jdeps 的结果只能作为参考，不能直接当真。
我建议采用一个保守的模块列表，先保证核心运行，再逐步裁剪。比如：
jlink \ --add-modules java.base,java.logging,java.naming,java.management,java.security.jgss,java.sql,jdk.crypto.ec,jdk.unsupported \ --strip-debug \ --no-header-files \ --no-man-pages \ --compress=zip-6 \ --output runtime然后用 jpackage 的--runtime-image runtime参数，让 jpackage 使用这个裁剪后的运行时，而不是当前 JDK 的完整运行时。
jpackage \ --type app-image \ --name DataBoard \ --input target \ --main-jar demo-data-board.jar \ --main-class org.springframework.boot.loader.JarLauncher \ --runtime-image runtime \ --dest dist这样做出来的 app-image，runtime目录会小很多。启动后如果能正常运行，再打安装包。
6.3 裁剪后哪些功能会悄悄失效
我的经验是，下面几类功能最容易在裁剪后出问题。
使用反射加载的类。比如 Jackson、MyBatis、Hibernate 这些库，很多地方通过反射获取构造函数或字段，当对应模块被剪掉后，运行时就会抛ClassNotFoundException或NoClassDefFoundError。解决方法通常是往--add-modules里补模块。
Java 加密扩展。如果应用涉及 HTTPS、JWT、加密算法，jdk.crypto.ec是必须的，但java.base并不包含它。默认模块列表里如果漏了这个，你会遇到各种“算法不可用”的异常。
JNDI 和命名服务。如果应用用了数据源、JNDI 连接池，java.naming必须保留。我有一次裁掉它之后，Spring Boot 的数据源初始化阶段直接报错，排查了很久才定位到。
JDBC 和 SQL 模块。java.sql必须保留，但如果你用的是某些数据库驱动，它们内部还会依赖java.xml或者java.management，这时候仅仅有java.sql还不够。
所以我的建议是，裁剪过程中频繁做冒烟测试。每次改一行--add-modules，就重新启动一次 app-image，把登录、查询、文件上传这些核心路径都过一遍。别一次性追求极致的体积，先把模块列表调到稳定，再考虑进一步瘦身。
7. 让安装包方案进一步适配真实分发场景
7.1 升级策略：安装包也可以做增量更新
安装包方案不等于“每次升级都要重新下载整个安装包”。如果你只是改了一个 Spring Boot 的业务 Jar，完全可以考虑把业务 Jar 和安装包启动器分离：安装包只负责放一个最小启动器，真正的业务 Jar 放在外部目录，升级时只替换这个 Jar 文件。
Spring Boot 的PropertiesLauncher可以提供这种灵活性，但实际操作起来要额外配置loader.path和MAIN环境变量，复杂度会上去一点。另一个更简单的思路是继续用可执行 Jar，但把它拷贝到用户可写的目录，启动器只负责调用系统 Java 或随包自带的java.exe。这个方案本质上回到了绿色版，但至少解决了运行环境问题。
我的建议是，如果应用还处于快速迭代期，不要急着把所有东西都固化进安装包。把配置、业务 Jar、日志目录逻辑拆分好，以后升级的压力会小很多。
7.2 把打包过程固化到 CI
手动执行 jpackage 一次两次没问题，时间一长肯定出错。我之前把打包流程写进了一个脚本，但每次换电脑、换 JDK 版本又出状况。后来改成 CI 流水线，提交代码打好标签后，流水线自动跑测试、打包、上传产物。
如果你也用 CI，记住一点：jpackage 不能跨平台打包，那就在流水线里同时配置三个平台的执行器，各自跑各自的打包命令，最终把产物归档。Linux 的打包步骤如果依赖rpmbuild，还需要在 CI 机器上安装对应的工具包，这些都应该提前固化成流水线环境。否则哪怕你本地跑通，CI 上一样会报缺工具的错误。
7.3 几个值得长期记住的经验
最后分享几个我这次踩完坑以后总结出来的经验。
执行顺序上，先 app-image，再安装包。任何启动问题都应该在 app-image 阶段解决，因为这时候最容易定位，也最容易重新跑测试。不要跳过这一步直接冲 MSI。
命名和版本号尽量规范化。安装包的应用名称、版本、供应商这些信息，在 Windows 卸载列表里会一直显示，以后做升级、做问题反馈时都需要靠它定位。如果版本号一直写 1.0.0，别人反馈问题时你根本不知道对方装的是哪一版。
日志路径永远不要依赖安装目录。安装包场景下，安装目录很可能没有写权限，或者目录在工作组策略中受保护。把日志默认输出到用户目录或系统日志目录，是一个非常值得提前做的事。否则应用一上线，第一个被用户提到的就是“为什么找不到日志”。
经历过这一轮之后，我给内部工具定下了一个通用打包模板：Windows 出 MSI，Linux 出 DEB，macOS 出 DMG，每个平台都先跑通 app-image，再封装安装包。jpackage 对我这种平时主要在服务端写代码的开发者来说，已经足够友好，只要你把它当成“一个生成启动脚本和各平台安装壳的工具”，而不是一个魔法黑盒，用起来就会顺畅很多。
