ytzxm上周一个同事找我，说手上有个内部工具要给客户现场演示，客户电脑是台干净的 Windows，没装 Java，双击 jar 包毫无反应，在那边干瞪眼。我远程看了一眼，直接甩了个用 Launch4j 打包好的 exe 过去，对方双击就起来了，全程不用装 JRE。这种场景在 Java 开发里太常见了：你在 IDE 里跑得好好的，交付给没有 Java 环境的用户时，一份 .jar 文件就是一道门槛。Launch4j 干的事情很简单——把 jar 包做成 Windows 双击可执行的 .exe，但它背后牵扯到的 JRE 搜索顺序、内存参数、图标版本信息、无 JRE 环境交付这些事，第一次上手的人基本都会踩坑。这篇就来聊聊我实际打包过程中反复折腾出来的经验，从原理到配置、从踩坑到自动化构建，一次说清楚。
1. Launch4j 到底是干什么的：一个启动器，不是一个编译器
1.1 jar 和 exe 之间到底差了什么
很多刚接触的人会有一个错觉：Launch4j 能把 Java 代码"变"成 Windows 能认识的原生程序。其实完全不是这回事。jar 本质上是一个 zip 压缩包，里面装的还是 .class 字节码，而 Windows 的 exe 需要的是 PE 格式的原生机器码。Launch4j 做的事，是生成一个瘦瘦的原生 Windows 可执行外壳，这个外壳没有任何业务逻辑，它唯一的工作是：
- 按你配置的规则去本机寻找 Java 运行时（JVM）
- 找到后把 jar 路径和 JVM 参数拼成一条类似
java -jar your.jar的命令 - 拉起 JVM，让 Java 代码在 JVM 里跑起来
所以你看，Launch4j 生成的 exe 不是把 jar "吃掉"了，它和 jar 是两个独立的文件。有人打包时把 exe 拷走了、jar 落在原地，结果双击报错，就是这个原因。理解这一点，后面所有配置就都顺了。
1.2 同类工具横评：Launch4j 和 exe4j、jpackage 有什么不一样
我先帮你把市面上常见的几条路捋清楚，免得选错方向白折腾。除了 Launch4j，常用的还有 exe4j、jpackage、GraalVM Native Image 和 JSmooth。
| 方案 | 原理 | 典型适用场景 | 优缺点一眼看 |
|---|---|---|---|
| Launch4j | 原生启动器壳，动态找/捆绑 JRE，启动时调用 java -jar | 有现成 jar、需要灵活控制 JVM 参数、想保留 jar 便于更新 | 免费开源，配置灵活，文档和资料多；exe 本体只是壳 |
| exe4j | 和 Launch4j 类似 | 企业级 GUI 工具，界面友好 | 个人免费但商业收费，一些高级配置藏在付费版 |
| jpackage | JDK 自带打包工具，支持捆绑精简运行时，生成 exe/msi | JDK 14+ 的自动模块化项目 | 官方方案，捆绑 JRE 方便，但定制启动行为不如 Launch4j 灵活 |
| GraalVM Native Image | 把 Java 字节码 AOT 编译成原生机器码 | 对启动速度和内存敏感、不想让用户碰 JRE | 是真编译，启动毫秒级，但部分反射/动态代理场景要额外配置，构建慢 |
我的建议是：如果你主导的项目是传统 Spring 或 Swing/JavaFX 桌面程序，手头已经有打好的 jar，想快速交付一个 Windows 下双击能跑的东西，Launch4j 是最省事的选择。它的配置文件是一个 XML，好改、好备份、好接入 CI。后面章节我会把它和 jlink 搭配起来，做出一个"不装 Java 也能跑"的绿色版，再配合 Maven 插件实现一键构建。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 拿到 Launch4j 之后：下载、安装和两种使用方式
2.1 用 GUI 界面生成第一个 exe
先去 SourceForge 上把 Launch4j 下载下来（认准 3.x 或 4.x 新版，老教程里的 3.9 界面差异很大），解压后你会看到几个关键文件：
launch4j.exe/launch4j.jar：GUI 配置界面launch4jc.exe：命令行工具，读 XML 配置demo目录：自带例子的配置，值得翻
GUI 使用流程基本是四步：
- 打开 launch4j.exe，切到 Basic 页签。
- 填上
Output file（生成的 exe 路径，比如dist/MyApp.exe）和Jar（你的 jar 路径，比如target/MyApp.jar）。 - 切到 JRE 页签，设好
Min/Max version，比如最小 1.8.0，这样用户机器上装了 Java 8 甚至更新版本都能跑。 - 点一下齿轮图标，Build 就完成了。
这四步看起来简单，但你实际用起来会发现问题：路径对不对、JRE 版本写没写、图标怎么没生效、内存参数设多少……下面几个小节逐个拆。
2.2 用 XML 配置文件和命令行模式干活
GUI 适合第一次快速验证，但一旦要批量改配置、交给同事协作或者进 Jenkins，GUI 就累赘了。Launch4j 会在你点 Build 的同时在旁边生成/更新一个 XML 配置文件，你可以把它理解成 GUI 的"源码"。命令行模式只需要一行：
bash复制launch4jc.exe path/to/config.xml
一个最简可运行的 XML 长这样：
xml复制<launch4jConfig>
<dontWrapJar>false</dontWrapJar>
<headerType>gui</headerType>
<jar>target/MyApp.jar</jar>
<outfile>dist/MyApp.exe</outfile>
<errTitle>MyApp - 启动错误</errTitle>
<icon>src/main/resources/MyApp.ico</icon>
<jre>
<minVersion>1.8.0</minVersion>
<maxVersion>17</maxVersion>
<initialHeapSize>256</initialHeapSize>
<maxHeapSize>1024</maxHeapSize>
</jre>
</launch4jConfig>
这里有个容易踩的坑：headerType 填 gui 还是 console。如果你的程序里有 System.out 输出，想双击后保留一个控制台窗口方便看日志，就用 console；如果不想弹黑框框，用 gui。这个选错，轻则看不到报错信息，重则你调试半天都不知道程序哪一步挂了。
3. 真正决定打包成败的配置项：JRE 搜索顺序、图标、启动参数
3.1 JRE 搜索顺序是头号坑
Launch4j 的 exe 启动后要去找本机的 JVM，它是按下面这套优先级来找的：
- 注册表里登记的 Java 运行时
- 配置文件中
<jre><path>指定的路径（支持绝对或相对路径） - 环境变量
JAVA_HOME - 系统
PATH中的java Launch4j内置的常见安装路径扫描
这个顺序在多数情况下够用，但恰恰是它导致了"我本机能跑、用户机器上死活起不来"的经典问题。举个真实例子：用户机器上装了 JDK 17，但注册表里残留着已经卸载掉的 JDK 8 的登记信息，Launch4j 按注册表找到 JDK 8 的路径去加载 jvm.dll，加载失败后并不会自动跳过，而是直接弹一个 "Cannot find Java" 或启动崩溃。
所以要养成一个习惯：在 <jre> 里把 <path> 配在最优先的位置。比如你把打包后的程序和 jlink 生成的精简 JRE 放在同一个目录下，就用相对路径：
xml复制<jre>
<path>runtime</path>
<minVersion>1.8.0</minVersion>
</jre>
相对路径是相对于 exe 所在目录解析的，这样整个目录拷到任何一台 Windows 上，exe 都会先去找旁边的 runtime 目录里的 JVM，不会受用户环境变量污染。这个"自带 JRE + 相对路径"的组合，是我交付内网工具的标配，后面第 5 章细说。
3.2 图标、版本信息、单实例、内存这些容易忽略的细节
很多人只填 Basic 页签三个框就点构建，其实这些细节才决定你交付的东西专不专业：
- 图标：Launch4j 只认
.ico格式，不认 png。你拿 png 直接改后缀名是不行的，会构建失败或图标变空白。用在线转换工具把 256x256 的 png 转成多尺寸 ico，效果最好。还想在 Windows 资源管理器的"详细信息"里看到版本号和公司名，就要去看 Version Info 页签，填上 File version、Product name、Company name。 - JVM 内存参数：建议只在 GUI 的 JRE 页签里写
Initial/Max heap size。这两个值会直接变成-Xms256m -Xmx1024m。桌面小工具我一般给 256m~1024m，够用又不会挤占系统内存。如果你有额外的 JVM 参数，比如-Dfile.encoding=UTF-8、-Dlog4j.configurationFile=config/log4j2.xml，统统写在<opts>节点里：
xml复制<jre>
<opts>
<opt>-Dfile.encoding=UTF-8</opt>
<opt>-Djava.net.preferIPv4Stack=true</opt>
</opts>
</jre>
- 单实例：如果你的程序是窗口应用，用户双击两次会出现两个进程，逻辑混乱还可能锁文件冲突。Launch4j 的 Single instance 页签可以设置 mutex 锁，核心就一项：
xml复制<singleInstance>
<mutexName>MyApp.SingleInstance.Mutex</mutexName>
<windowTitle>MyApp 已在运行</windowTitle>
</singleInstance>
这个 mutex 是 Windows 内核对象名，全局唯一就行。用户再次双击时，弹窗提示而不是开第二个进程。
- 启动失败时的兜底：当系统里确实没有任何可用 JRE 时，Launch4j 会用
errTitle和你配置的downloadUrl弹一个提示框，告诉用户去哪里装 Java。这个看起来不起眼，但对没有 Java 概念的普通用户来说，比一片空白的"找不到 jvm.dll"友好得多。
3.3 相对路径和引号：用户把程序装在带空格的目录里怎么办
这是典型的 Windows 交付问题。假设你的程序装在 C:\Program Files\My Tool\ 下面，启动器拼命令行时路径里有空格，没加引号必挂。Launch4j 的做法是自动处理一部分，但你自己配置 jar 路径、工作目录、日志文件路径时也要留个心眼。
一个可靠的做法是：在工作目录相关的配置里，优先用编译期就能确定的内部相对路径，比如 logs/、config/，让程序内部用 user.dir 去定位资源。如果有外部参数，比如要读取 exe 同目录下的文件，代码里尽量通过 System.getProperty("user.dir") 来推导，而不是写死 C:\...。
如果你用 <jre><path> 指向相对路径，Launch4j 会自动帮你转成绝对路径并处理引号。但我还是建议你有空在带空格和中文的路径下完整跑一遍启动流程，一次性把问题暴露出来，别等客户现场炸。
4. 打包完双击就闪退：用日志和错误码定位问题
4.1 闪退的几种典型症状
这是我被问得最多的一类问题。说"闪退"其实信息量很少，因为不同的启动失败阶段，错误表现完全不同：
| 症状 | 原因通常在哪 |
|---|---|
| 黑色窗口一闪而过，什么提示都没有 | 启动器没找到 JRE，或者 headerType 用 gui 但程序自己抛了未捕获异常 |
| 提示 "Failed to find Java Virtual Machine" | Launch4j 搜索 JRE 失败，注册表、JAVA_HOME、PATH 都没有符合条件的版本 |
| 提示 "Could not find main class" | jar 里的 MANIFEST.MF 没写 Main-Class，或者写错了类名 |
| 程序启动后有窗口，但业务代码一运行就崩 | 多半是依赖的类、配置文件、外部库没放到 jar 里，ClassNotFoundException |
| 报错 "Not valid Win32 application" | exe 位数和 JVM 位数不匹配的旧版问题，新版不用太担心 |
4.2 一个真实的排查过程：从黑框到定位到 jar 依赖缺失
我自己排过最典型的一个案例：用户双击 exe 后黑框一闪就消失，什么消息都没有。这种场景下第一件事是让错误暴露出来。Launch4j 有很朴素的调试手段——把 headerType 改成 console，重新构建一份 exe，然后在命令行里直接运行：
bash复制C:\dist>MyApp.exe
这时控制台窗口不会关闭，Java 异常堆栈会直接打在屏幕上。我当时看到的是：
code复制Error: Could not find or load main class com.example.Main
Caused by: java.lang.ClassNotFoundException: com.example.Main
这就把问题缩小到 jar 的 Main-Class 没有配对。我打开 jar 的 MANIFEST：
bash复制jar xf MyApp.jar META-INF/MANIFEST.MF
type META-INF\MANIFEST.MF
发现 Main-Class 写的是 com.example.Main，但 class 文件实际在 com/example/v2/Main.class，显然是构建脚本里配错了。修正后重新打包，启动正常。
这类问题其实有个更快的定位方法：在神秘闪退的配置文件里加一个 Java 参数 -Dlaunch4j.debug=true（这是 Launch4j 的隐藏调试开关，打开后日志会写到 exe 同目录下的 launch4j.log）。但我个人还是推荐控制台方式，因为能看到完整的 JVM 堆栈。
4.3 启动日志和 JVM 参数排查要点
如果你怀疑是 JVM 参数问题，可以用环境变量 JAVA_TOOL_OPTIONS 提前注入参数。这个是 JVM 自己读的，加上后不需要改 Launch4j 配置，就能看到你注入的 JVM 参数是否生效。比如：
bash复制set JAVA_TOOL_OPTIONS=-Xlog:gc
MyApp.exe
如果程序是 GUI 应用，不想弹黑框，也可以让它把日志写到文件：
xml复制<jre>
<opts>
<opt>-Dlog4j2.configurationFile=config/log4j2.xml</opt>
<opt>-Dcom.example.log.dir=logs</opt>
</opts>
</jre>
再配合 log4j2 的 file appender，出问题从日志文件里翻，比问用户"你看到了什么报错"靠谱一百倍。桌面程序尤其要养成写日志的习惯，线上用户永远描述不清楚错误，只能给你一个截图或一句"它就是不工作"。
5. 没有 JRE 也能跑：jlink 精简运行时和 Launch4j 配合
5.1 为什么单靠 Launch4j 还不够
前面反复提到，Launch4j 只是个启动器，最终还是要找 JVM。那问题就来了：如果你的用户是普通业务人员，你总不能要求他们先装个 JDK 吧。这就是"绿色免安装版"的需求来源。传统做法是把整个 JDK/JRE 目录拷到程序旁边，但 JRE 少说几百兆，太大了。JDK 9 之后官方给了一个精简运行时工具——jlink，它能把 Java 模块裁剪成刚好够用的一小堆文件，我实际做过最小的 Swing 应用运行时只有 40MB 左右，比整个 JRE 小了一个数量级以上。
5.2 用 jdeps 推导模块依赖并生成运行时
先说个简单的场景：你的项目是传统 classpath 应用（不是 module-info.java 那一套），也可以交给 jlink 处理。我用两个命令来完成：
bash复制jdeps --ignore-missing-deps --print-module-deps target/MyApp.jar
这条命令会分析 jar 包里的字节码，输出它依赖的 JDK 模块列表，比如可能是：
code复制java.base,java.desktop,java.logging,java.naming,java.sql
然后把这些模块喂给 jlink：
bash复制jlink --module-path "%JAVA_HOME%\jmods" \
--add-modules java.base,java.desktop,java.logging,java.naming,java.sql \
--strip-debug --no-header-files --no-man-pages \
--compress=zip-6 \
--output dist/runtime
生成的 dist/runtime 目录里就有 bin\server\jvm.dll，Launch4j 就是靠这个文件来拉起 JVM 的。
有几个要点我得特意强调：
jdeps的输出要人工审视，尤其你的程序用了反射、SPI、动态代理、Class.forName，它可能分析不出来，会导致 jlink 出来的运行时缺模块，运行中抛ClassNotFoundException。没把握就多加上几个：java.management、java.instrument、jdk.unsupported。--compress=zip-6是老版本 jlink 的可选项，压缩率还不错；新版 JDK 里有些参数被标记为 deprecated，但产物照样能用。- 生成完以后，用
runtime\bin\java -jar MyApp.jar先试一把，确定精简运行时能跑，再交给 Launch4j。
5.3 目录规划、相对路径和"exe 不带 jar"的误解
这是我踩过最深的坑，专门拿出来讲。第一次做免安装版时，我把程序目录做成了：
code复制MyApp/
├── MyApp.exe
├── MyApp.jar
└── runtime/
然后 Launch4j 的 <jre><path> 配成 runtime，Launch4j 能识别 exe 旁边的 runtime 目录。这里有个关键点：Launch4j 找 JVM 时，需要的是 runtime\bin\server\jvm.dll 存在，jlink 生成的目录正好符合这个结构，所以配置很简单：
xml复制<jre>
<path>runtime</path>
</jre>
还有一种玩法是把 jar 也"藏"起来，不想让普通用户直接看到 jar 文件。没关系，Launch4j 支持 dontWrapJar 选项，配合自定义 classpath，把 jar 放在一个隐蔽的子目录里。不过要诚实说一句：这只是提高使用门槛，并不能防破解，jar 还是在那儿，懂行的人照样能解开看。真正的安全性后面第 7 章讲。
另外注意一下，path 的解析基准是 exe 所在目录，不是当前工作目录。用户在资源管理器里双击和从命令行别的路径启动，工作目录不同，但相对路径的解析不会变，这是 Launch4j 做得比较稳的地方。
如果你把 exe 和 runtime 目录放在同一个目录，但用户把整个目录拷到了类似 C:\Users\张三\Desktop\内部工具 这种带中文和空格的路径下，Launch4j 和高版本 JDK 都做了比较好的兼容，我实测过没问题。但如果你发现程序启动时加载不到配置或日志，先检查代码里是不是用了硬编码路径。
6. 接入 CI：用 Maven 插件和命令行做一键构建
6.1 launch4j-maven-plugin 的基础配置
手动点 GUI 构 build 一两次还行，一旦你的项目到了要频繁发版的阶段，打包流程必须是自动化的。Launch4j 官方支持通过 Maven 插件直接集成进构建流程。常用的插件坐标是：
xml复制<plugin>
<groupId>com.akathist.maven.plugins.launch4j</groupId>
<artifactId>launch4j-maven-plugin</artifactId>
<version>2.5.2</version>
<executions>
<execution>
<id>build-exe</id>
<phase>package</phase>
<goals>
<goal>launch4j</goal>
</goals>
<configuration>
<headerType>gui</headerType>
<jar>${project.build.directory}/${project.build.finalName}.jar</jar>
<outfile>${project.build.directory}/MyApp.exe</outfile>
<icon>${project.basedir}/src/main/resources/MyApp.ico</icon>
<errTitle>启动失败</errTitle>
<downloadUrl>https://bell-sw.com/pages/downloads/</downloadUrl>
<jre>
<minVersion>1.8.0</minVersion>
<maxVersion>17</maxVersion>
<path>runtime</path>
<opts>
<opt>-Dfile.encoding=UTF-8</opt>
</opts>
</jre>
<singleInstance>
<mutexName>MyApp.SingleInstance.Mutex</mutexName>
</singleInstance>
</configuration>
</execution>
</executions>
</plugin>
把这个插件绑定到 package 阶段后，你只要 mvn clean package，target 目录下就会同时出现 jar 和 exe。配上 jdeps + jlink，可以做成构建脚本的一部分，在 Maven 里用 exec-maven-plugin 调用 jlink，也可以直接写 Jenkins pipeline 在打包机上执行。
6.2 构建脚本里容易忽略的三个问题
问题一：构建机和打包环境的 JDK 版本必须尽量接近生产版本。 有一次我在 JDK 17 上打出 exe，<minVersion> 写的 1.8，结果用户机器上只有 JDK 8，启动时因为 --add-opens 相关参数不兼容直接崩了。后来我统一规范：构建机固定用目标机器最常见的 JDK 版本，或者 minVersion 写得准一些。
问题二：Maven plugin 不会自动帮你把 runtime 目录拷过去。 插件只负责生成 exe。如果你用了 jlink 生成 runtime，需要在 maven-antrun-plugin 或 assembly 里额外把 runtime 目录复制到 target。我常用 maven-resources-plugin 的 copy-resources 或者直接把 runtime 作为构建机上的固定目录交给脚本拷贝，效果都一样。
问题三：CI 机上没有图形界面也能构建。 这是 Launch4j 一个很良心的设计，命令行工具 launch4jc.exe 完全不依赖 GUI，所以 Jenkins/GitLab CI 的 Windows agent 里可以直接跑。如果你在 Linux 的 CI 上构建 Windows exe，那不行，Launch4j 只能在 Windows 环境运行。不过现在很多团队用 GitHub Actions 的 Windows runner，随便跑。
7. 聊聊两个绕不开的话题：杀毒误报和反编译风险
7.1 为什么 Launch4j 生成的 exe 容易被杀毒软件盯上
先说一个扎心的事实：Launch4j 生成的是原生启动器壳，不是常见的微软编译器产物，它启动 JVM 的方式是通过加载 jvm.dll 并在内存里构造调用，这个过程和某些恶意软件的注入行为很像。再加上很多人喜欢从网上下载的"绿色版"、破解版工具，杀毒软件对这类来自互联网的未知签名 exe 本来就敏感。结果就是：同一个 jar 用 JDK 的 jar 命令放着没事，一打包成 exe 就被各种杀软报毒。
我实际处理过的办法，按有效性排序：
- 代码签名证书：花钱买一个 Windows 可信任的代码签名证书，签名后的 exe 的 SmartScreen 拦截会少很多。现在有些免费证书（比如 Open Source SignFund）可以申请，但不一定覆盖企业分发场景。这是最治本的手段。
- 关闭压缩/加壳选项：Launch4j 的某些版本构建选项里有对 exe 做压缩处理的开关，压缩会显著提高误报率。如果不需要压缩，就关掉。具体在 GUI 的 "Exe" 选项页里看清楚再选。
- 改为 jpackage 或 Native Image：如果你实在被杀毒软件折腾得不行，换工具也是一种解法。jpackage 打出的安装包在误报方面比 Launch4j 好不少，因为它是 JDK 官方的产物，同时它自带捆绑 JRE 的能力。GraalVM 原生镜像打出来的 exe 几乎不会被误报，代价是构建过程复杂、对框架有要求。
- 向杀毒厂商申诉：自己用工具比如 VirusTotal 查完，误报的话把结果反馈给各厂商。这个过程比较慢，适合产品要正式公开分发的场景，内网自用不太划算。
7.2 exe 不等于源码安全：反编译和代码保护
热词榜上挂着"反编译jar""exe反编译看到源码"，说明很多人有个误解：打成 exe 后 Java 代码就安全了。真相是：jar 就是 zip，unzip 一解就能看到 class 文件，用 JD-GUI、FernFlower 或 Procyon 反编译，还原出来的代码虽然注释没了、局部变量名乱了（如果你没做混淆），但核心逻辑基本能读懂。Lauch4j 的 exe 只是把 jar 包着，没有加密、没有混淆，懂一点的人照样能抽出 jar 反编译。
如果真的有保护需求，我的建议是按威胁程度来分级：
- 只是防路人顺手看：jar 放在看起来不那么显眼的目录，配合 Launch4j 的
dontWrapJar，够了。 - 防一般开发者：上 ProGuard/R8 混淆。混淆后类名、方法名变成 a/b/c，阅读成本大幅提高。注意要保留
Main-Class和反射用到的类名，不然启动时直接NoClassDefFoundError。 - 防专业逆向：说实话 Java 生态做不了绝对安全，最彻底的方案是把核心算法模块用 GraalVM Native Image 编成原生库，再通过 JNI 或 HTTP 服务调用；或者干脆把核心逻辑放服务端。纯桌面包保护到头也就提高门槛，防不了真正铁了心的逆向。
我自己的经验是：大多数内部工具的源代码泄露风险根本不在打包这一步，而是团队里谁都能拿到 jar、随手往网盘一传。与其把精力耗在加密混淆上，不如做好权限管理和分发渠道，这比任何打包保护都有用。
最后分享一个实用小技巧：不管你用什么方式打包，发出去之前一定拿一台"干净得像白纸一样"的 Windows 虚拟机测一遍启动流程，装上杀毒软件测一遍误报，再模拟一下 C 盘 / 中文目录 / 空格目录几种路径。把该踩的坑留在自己这边踩完，别等用户替你踩。打包工具选 Launch4j 还是 jpackage，不是关键；关键是搞清楚你的 exe 是怎么找到 JVM 的、日志从哪里看、依赖怎么带全，这套思路在任何打包方案下都通用。