本文旨在解决使用jpackage在windows上打包java应用时，因错误配置运行时环境导致的可执行文件无法启动问题。核心在于，jpackage的`--runtime-image`参数应指定由同一jdk版本下的jlink工具生成的模块化运行时镜像，而非直接引用旧版jre。文章将详细阐述正确的jlink与jpackage配合使用方法，确保应用顺利打包与运行。
理解jpackage与运行时环境
jpackage是JDK 14及更高版本提供的一个工具，用于将Java应用程序打包成本地安装包（如Windows的.exe、macOS的.dmg、Linux的.deb或.rpm）。它允许开发者将Java应用程序及其所需的Java运行时环境（JRE）捆绑在一起，从而使得用户无需预先安装Java环境即可运行应用。
在打包过程中，jpackage通过--runtime-image参数指定应用程序将使用的Java运行时环境。然而，一个常见的错误是尝试将一个传统的、非模块化的Java 8 JRE直接作为运行时镜像提供给一个由新版JDK（例如JDK 17）运行的jpackage命令。这会导致生成的可执行文件在运行时出现诸如“Error: Registry key 'Software\JavaSoft\Java Runtime Environment'\CurrentVersion' has value '1.8', but '' is required.”或“Error: could not find java.dll”等错误，最终无法启动。
这些错误的核心原因在于：
- 版本不匹配： jpackage工具本身运行在一个较新的JDK版本上，而提供的运行时镜像却是旧版Java 8 JRE，两者内部结构和预期行为不兼容。
- 结构差异： Java 9及以后版本引入了模块化系统（JPMS），传统的Java 8 JRE并未遵循这一模块化结构。jpackage期望的运行时镜像应是模块化且由jlink工具生成的。
正确构建运行时镜像：使用jlink
为了确保jpackage生成的应用程序能够正确运行，我们必须使用与jpackage所用JDK版本一致的jlink工具来创建自定义运行时镜像。jlink工具能够根据应用程序实际所需的Java模块，生成一个精简且模块化的运行时环境。
立即学习“Java免费学习笔记（深入）”；
1. 使用jlink生成自定义运行时镜像
首先，确定你的应用程序依赖哪些Java模块。对于大多数桌面或控制台应用，java.base是必需的，如果涉及图形界面，可能还需要java.desktop等。你可以通过jdeps工具来分析应用程序的模块依赖，或者根据经验选择常用模块。
以下是使用jlink创建一个包含基本模块的运行时镜像的示例命令。假设你正在使用JDK 17，并且希望将运行时镜像存放在名为my-jre的目录中：
"C:\Program Files\Java\jdk-17.0.5\bin\jlink" ^ --module-path "C:\Program Files\Java\jdk-17.0.5\jmods" ^ --add-modules java.base,java.desktop ^ --output my-jre ^ --compress=2 ^ --no-header-files ^ --no-man-pages
命令解析：
- "C:\Program Files\Java\jdk-17.0.5\bin\jlink": 指定jlink工具的路径。确保它与你运行jpackage的JDK版本相同。
- --module-path "C:\Program Files\Java\jdk-17.0.5\jmods": 指定JDK模块的路径。
- --add-modules java.base,java.desktop: 添加应用程序所需的Java模块。根据你的应用需求添加更多模块，例如java.logging、java.sql等。
- --output my-jre: 指定生成的运行时镜像的输出目录。
- --compress=2: 对运行时镜像进行压缩，减小最终文件大小。
- --no-header-files和--no-man-pages: 排除不必要的头文件和手册页，进一步减小镜像体积。
执行此命令后，会在当前目录下生成一个名为my-jre的目录，其中包含了精简且模块化的Java运行时环境。
2. 使用jpackage打包应用程序
有了jlink生成的自定义运行时镜像后，就可以将其作为--runtime-image参数的值传递给jpackage命令。
"C:\Program Files\Java\jdk-17.0.5\bin\jpackage" ^ --name test-installer ^ --input . ^ --main-jar test.jar ^ --runtime-image my-jre ^ --main-class com.xxxxx.Main ^ --win-console
命令解析：
- "C:\Program Files\Java\jdk-17.0.5\bin\jpackage": 指定jpackage工具的路径，同样需要与jlink所用JDK版本一致。
- --name test-installer: 指定生成的安装包和应用程序的名称。
- --input .: 指定应用程序JAR文件所在的目录。
- --main-jar test.jar: 指定应用程序的主JAR文件。
- --runtime-image my-jre: 关键步骤，指向之前通过jlink生成的自定义运行时镜像目录。
- --main-class com.xxxxx.Main: 指定应用程序的主类。
- --win-console: （可选）对于控制台应用程序，此选项可以确保在Windows上运行时显示控制台窗口。
执行此命令后，jpackage将使用my-jre中包含的运行时环境来打包你的应用程序，生成一个功能完整的、可运行的Windows安装程序。
注意事项与最佳实践
- JDK版本一致性： 始终确保用于运行jpackage命令的JDK版本与用于jlink创建运行时镜像的JDK版本完全一致。这是避免运行时兼容性问题的最重要原则。
- 模块选择： 在使用jlink时，精确选择应用程序所需的模块。添加不必要的模块会增加运行时镜像的大小。可以使用jdeps工具来分析应用程序的模块依赖。
- 路径管理： 在命令行中指定路径时，特别是包含空格的路径，请使用双引号将其括起来。
- 跨平台考虑： jlink生成的运行时镜像是平台特定的。如果你需要为不同的操作系统打包应用程序，需要针对每个目标平台分别运行jlink和jpackage。
- 调试： 如果打包后应用程序仍然无法运行，首先检查控制台输出的错误信息。这些信息通常能直接指出问题所在。其次，确保--main-jar和--main-class参数指向正确的文件和类。
总结
通过本文的指导，我们明确了使用jpackage打包Java应用程序时，正确配置运行时环境的重要性。核心在于利用与jpackage相同JDK版本下的jlink工具，创建定制化的模块化运行时镜像，并将其作为--runtime-image参数传递。遵循这一流程，可以有效避免因Java环境兼容性问题导致的可执行文件无法启动，从而确保Java应用程序在Windows平台上的顺利部署和运行。
