Java jpackage 打成安装包命令-马育民老师

# 介绍

`jpackage` 是 **JDK14 正式引入（JEP 392）** 的官方打包工具，用于把 Java 应用打包成**自带JRE的原生安装包**，用户电脑**不需要提前安装Java**就能直接安装运行。

# 原理

内部自动调用 `jlink` 裁剪生成精简JRE，将你的jar/模块、依赖、裁剪JRE一起打包，生成当前操作系统的原生安装程序。

### 限制：不支持跨平台打包

- Windows 只能打包 exe / msi
- macOS 只能打包 dmg / pkg
- Linux 只能打包 deb / rpm

想要多平台安装包，必须在对应操作系统上分别构建。

# 支持输出包格式

| 平台 | 输出类型 |
|---|---|
| Windows | `.exe`、`.msi` |
| macOS | `.dmg`、`.pkg` |
| Linux | `.deb`（Debian/Ubuntu）、`.rpm`（CentOS/RHEL） |

另外支持 `--type app-image`：只生成解压即用的目录（绿色免安装，不是安装程序）

# 前置依赖
1. **JDK ≥14**，推荐 JDK17+/21 LTS；**必须使用JDK，JRE不带jpackage**
2. Windows额外依赖：**WiX Toolset 3.8+**（生成msi需要，exe可以不用），安装后加入PATH，`candle /?` 验证
3. macOS：需要Xcode命令行工具，签名打包需要开发者证书
4. Linux：打包deb/rpm需要对应系统打包工具（dpkg/rpmbuild）

# 打包模式
### 1）非模块化项目（普通jar，SpringBoot fatjar 属于这类）
```bash
jpackage --name MyApp \
--input ./libs \
--main-jar myapp.jar \
--main-class com.demo.Main \
--app-version 1.0.0 \
--dest ./output \
--icon app.ico \
--win-shortcut
```
- `--input`：存放jar和资源文件的目录
- `--main-jar`：主jar包
- `--main-class`：入口类，如果jar的MANIFEST已经写好main-class，可省略

### 2）模块化Java项目（module-info.java）
```bash
jpackage --name MyModApp \
--module-path ./mods \
--module demo.module/com.demo.Main \
--app-version 1.0.0
```
- `--module-path / -p`：模块路径
- `--module / -m`：`模块名/主类名`

# 常用参数
| 参数 | 说明 |
|---|---|
| `--name` | 应用显示名称 |
| `--app-version` | 版本号 |
| `--vendor` | 开发商/供应商 |
| `--description` | 软件描述 |
| `--copyright` | 版权信息 |
| `--dest` | 输出目录 |
| `--icon` | 图标：Windows `.ico`，macOS `.icns`，Linux `.png` |
| `--type` | 指定输出类型：`exe/msi/dmg/pkg/deb/rpm/app-image` |
| `--java-options` | JVM启动参数，例如 `--java-options "-Xmx512m"` |
| `--arguments` | 程序默认启动参数 |
| `--win-shortcut` | Windows安装后创建桌面快捷方式 |
| `--win-menu` | Windows开始菜单创建条目 |
| `--win-dir-chooser` | Windows安装包允许用户选择安装目录 |
| `--file-associations` | 关联文件后缀（例如双击 .myext 文件打开本程序） |
| `--add-launcher` | 多启动器，一个包内多个入口程序 |

查看完整帮助：
```bash
jpackage --help
```

# 打包流程简述
1. 准备好你的应用jar/模块、资源文件放到input目录
2. jpackage 内部调用 jlink，**只打包程序用到的模块**，生成精简JRE（体积远小于完整JDK）
3. 组装应用镜像（app-image目录，包含jre、jar、启动脚本、配置文件）
4. 基于app-image，编译生成对应平台的安装包（exe/msi等）

可以分两步：先生成app-image，手动修改里面文件，再打包成安装包，适合需要自定义脚本、配置文件场景。

```bash
# 第一步：只生成绿色app-image文件夹
jpackage --type app-image --name MyApp --input libs --main-jar myapp.jar
# 修改app-image内文件
# 第二步：基于app-image打包成exe
jpackage --name MyApp --app-image ./MyApp --dest output
```

# 优缺点
### 优点
1. JDK官方工具，无需第三方打包工具（launch4j、excelsior jetc等）
2. 自带裁剪JRE，用户无需装Java
3. 原生安装包，支持桌面快捷方式、开始菜单、文件关联、版本信息、图标
4. 支持模块化与普通Jar，支持多启动器
5. 配合jlink，JRE体积可控

### 缺点
1. **不能跨平台打包**，Windows只能打包Windows程序
2. Windows生成MSI依赖WiX，增加环境准备成本
3. 打包产物体积仍然偏大（相比GraalVM native-image）
4. 不支持AOT编译，仍然是JVM运行模式
5. SpringBoot大胖jar打包会有坑，需要额外处理

# 与同类工具对比
1. launch4j：仅把jar包装成exe，**不带JRE**，需要附带jre文件夹；只能Windows
2. jpackage：官方，自动裁剪JRE，多平台安装包；需要对应平台构建
3. GraalVM Native Image：直接编译为原生机器码，无JRE，体积最小；编译成本高、很多库不支持
4. Excelsior JET：商业AOT工具

# 常见踩坑
1. 路径不要带中文/空格，容易打包失败
2. 图标格式严格对应平台，格式错误会静默跳过图标
3. Windows WiX安装后，必须把wix的bin目录加入系统PATH，否则无法生成msi
4. jpackage必须用JDK，不能用JRE执行
5. 打包输出目录最好是空目录，旧文件会被复用引发异常
6. 防火墙/杀毒软件可能拦截exe生成

原文出处：/show_1GW4CZYl1W5Z.html