我先说个场景：你辛苦写了一个Java小工具，想发给同事或者朋友用，结果对方电脑上没有装JDK，双击你给的jar包只会弹出一个“选择打开方式”的窗口，或者闪一下黑框就没了。这种尴尬我在刚做Java桌面开发时经历过无数次，最后基本都是老老实实让人家装个JDK才把程序跑起来。后来我找到launch4j，这个问题才算真正解决。launch4j是一个把Java jar包包装成Windows exe可执行文件的开源工具，它不修改你的class文件，也不做加密混淆，只是在你的jar外面套一个原生程序壳，双击exe后由这个壳自动去调用本机JRE，再把参数传给java启动你的程序。这篇文章是我多次亲测后的完整记录，从原理讲到每个配置字段，连踩坑记录一起给你，适合正在做Java桌面应用分发、或者想给内部工具做个免命令行启动方式的人参考。
1. launch4j到底解决了什么问题，为什么分发Java程序离不开它
1.1 jar和exe之间的那道坎
Java程序编译打包后的自然产物是jar包，它在服务器后端跑得好好的，直接java -jar xxx.jar就行。但到了Windows桌面场景，问题全冒出来了：不是所有用户都习惯开命令行，更不是所有电脑都装了JRE。要让一个不懂技术的用户跑起你的程序，你得让他先装Java运行环境，再让他记住“打开cmd，cd到目录，然后输入java -jar xxx.jar”这么一串操作，这显然不现实。
launch4j的思路是绕过这个过程：它生成一个很小的原生exe，用户双击这个exe，壳程序自动在本机搜索Java运行时，找到之后把类路径、启动参数、JVM参数都给你配好，再启动你的Java程序。注意它并不是把字节码重新编译成机器码，你的程序逻辑仍然跑在JVM里，所以对“exe”这个结论要打个折，它更像是一个启动器launcher，但这个启动器解决了用户侧的绝大部分体验问题。
1.2 同类工具横向对比，为什么我最终选了launch4j
我实际用过的方案不止launch4j一个，这里把主流几条路线放在一起对比过：
| 方案 | 原理 | 优点 | 缺点 |
|---|---|---|---|
| launch4j | 原生壳调用JVM运行jar | 配置灵活、开源免费、体积小、支持命令行与XML配置 | 需要目标机有JRE，或自行捆绑 |
| exe4j | 同为外壳启动器 | 界面向导化、文档全 | 商业授权，个人版有限制 |
| jpackage（JDK自带） | JDK 14+官方打包工具，可生成安装包和运行时镜像 | 官方维护、可捆绑JRE | 对旧项目结构有一定要求 |
| GraalVM Native Image | 提前编译为原生可执行文件 | 启动快、无JVM依赖 | 反射/动态代理要额外配置，踩坑成本高 |
| 批处理+工具转换 | 把start.bat转成exe | 成本最低 | 黑窗口残留、不优雅，本质还是命令启动 |
launch4j的优势在于“轻”和“可控”。它本身只有几MB，打包出来的exe也就几百KB到几MB，加不加图标、要不要splash页、JVM参数怎么传，全都在一个配置文件里写死，特别适合团队内部工具的快速分发，也适合企业系统里那种“双击登录桌面端”的客户端入口场景。GraalVM那种方案虽热，但遇到反射框架、动态代理多的项目，光是调整配置就能耗掉你一个下午。如果只是想解决“用户双击能跑”这个问题，launch4j是性价比最高的。
2. 打包前准备：从一个能正常运行的jar开始
2.1 确认JDK版本与编译目标
拿launch4j打包之前，我强烈建议先确认三件事：你的项目用哪个JDK版本编译、目标用户机器上可能装什么版本的JRE、你的代码里有没有用到非标准库。launch4j有一个jreMinVersion和jreMaxVersion的配置，如果你用JDK 17的新特性编译，却在配置里写了最低支持JRE 8，那用户机器上只有JRE 8时就会出现class版本错误。我一般习惯把编译目标设置为1.8，代码里也尽量避开太新的API，这样兼容范围最广。如果你的项目已经上了JDK 17以上，建议直接用--release 8或者--release 11编译并测试跑通，再考虑分发细节。
另外一个容易忽略的点是系统架构。Windows有32位和64位之分，你的exe默认会去找同架构的JRE。如果你的客户还有老式32位机器，那打包时就得考虑打两份，或者让launch4j的runtime检测逻辑放开一点。我实际项目里基本只做64位，因为老机器真的越来越少了。
2.2 用Maven打出一个能直接java -jar跑的包
launch4j再怎么包装，前提是你的jar能够用java -jar xxxx.jar正常启动。这一步很多人栽过跟头：明明IDE里能跑，打出来的jar双击却报“no main manifest attribute”。原因是Maven默认打的jar包manifest里没有主类信息。我通常用maven-shade-plugin，它能把依赖全部打进去，还能指定Main-Class：
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-shade-plugin</artifactId> <version>3.2.4</version> <executions> <execution> <phase>package</phase> <goals><goal>shade</goal></goals> <configuration> <transformers> <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer"> <mainClass>com.example.MainApp</mainClass> </transformer> </transformers> <filters> <filter> <artifact>*:*</artifact> <excludes> <exclude>META-INF/*.SF</exclude> <exclude>META-INF/*.DSA</exclude> <exclude>META-INF/*.RSA</exclude> </excludes> </filter> </filters> </configuration> </execution> </executions> </plugin>这段配置里排除META-INF签名文件是个关键操作，否则多个依赖混合到一个jar里时，偶尔会报SecurityException: Invalid signature file digest for Manifest main attributes。打完包之后，先在命令行验证一下：
java -jar target/your-app.jar能正常起来再进入launch4j环节。如果这一步都过不了，后面所有的问题都会叠加在exe身上，排查起来非常痛苦。另外，如果你的项目是Spring Boot，直接用spring-boot-maven-plugin打的jar也是可以的，launch4j不关心你的jar内部结构，它只要求这个jar能被java -jar启动。
3. 图形界面配置详解：每个字段到底是干什么的
3.1 基本配置页：输出文件、jar路径与图标
launch4j启动后是图形界面，第一页“Basic”里最核心的字段有四个。Output file是生成的exe保存路径，Jar是你打包好的jar路径，Icon是exe图标文件，必须是.ico格式而不是常见的png。这里有个坑：输出exe的文件名不要和jar同名，也不要把exe放在jar同一个目录还叫一样的名字，否则launch4j写入文件时可能因为目标文件被占用而失败。我习惯把exe输出到dist/目录下，jar留在target/里，两者物理隔离，后续做安装包也方便直接拿dist目录做素材。
还有一个经常被忽略的选项叫Dont wrap jar，勾选后exe不把jar“内含”到自身，而是运行时去相对路径下找jar文件。这个模式的好处是替换程序逻辑只需要换jar，不需要重新生成exe；坏处是分发时要带两个文件。我一般在自己维护的工具里用这个模式，面向客户的场景则取消勾选，让程序seal成一个单一exe文件，交付体验最好。
3.2 JRE设置页：版本范围、堆内存与JVM参数
真正让launch4j区别于简单批处理的地方在“JRE”这一页。我逐个说下我常用的配置：
Minimum version/Maximum version：控制壳程序去找哪个范围的Java版本。最低版本我填1.8.0，最高版本往往留空，避免限制了用户在电脑上装了更新的JDK而无法启动。Initial heap size/Max heap size：对应-Xms和-Xmx。这里有一个计算逻辑：如果你的程序最多需要2GB内存，而目标机只有4GB，你把Max heap size写成4096是很危险的，启动就会创建失败。我一般先按自己机器压测出峰值，再留50%余量。比如桌面工具峰值用600MB，我就写成1024m。JVM options：填-Dfile.encoding=UTF-8、-Dlog4j.configurationFile=...这些附加参数。Windows中文环境下不加-Dfile.encoding=UTF-8，日志和界面乱码的概率极高，这是中文项目的一个经典痛点。
还有一个Runtime bits选项，可以指定只找64位或者32位的JVM。如果你的程序用到了JNI本地库，那这个选项务必要设置准确。比如你打了64位的dll，exe却优先找到了32位JRE，跑起来会直接报UnsatisfiedLinkError。
3.3 高级选项：单实例、启动画面、环境变量
到“Header”和“Single instance”两个子页里，有几个细节值得说。Single instance这个功能对很多内部管理系统特别实用，勾选后用户重复双击exe，launch4j会检测到已有实例，不会再开第二个进程。它默认的机制是通过文件锁实现，如果你需要第二个实例启动时通知第一个实例，可以开启Single instance下的Message配置，设置一个窗口消息值，程序里监听即可。
Splash启动画面是用一张bmp图片作为程序加载期间的过渡页，对Java这种启动需要一两秒的场景很友好。注意它只支持特定的bmp格式，直接用jpg改后缀不行，网上搜“bmp 24位转换”就能找到工具，我一般用画图另存为24位bmp就行。Environment variables字段可以设置exe启动时的环境变量，格式是KEY=VALUE拼接，用分号分隔。这里我踩过坑：变量值里如果带空格，一定不要加额外引号，launch4j自己会处理。
4. 脱离图形界面：用XML配置和命令行做自动化打包
4.1 launch4j.xml配置结构
图形界面适合第一次摸索，但真正到了发版阶段，我强烈建议你把配置保存成XML文件。launch4j的所有配置都存在一个XML里，保存路径在File -> Save configuration。这样你可以把配置文件提交到git里，团队每个人都能用同一条命令打出完全一致的exe，不会因为谁在界面上多勾了一个选项就产生交付差异。我常用的XML结构长这样：
<launch4jConfig> <dontWrapJar>false</dontWrapJar> <headerType>gui</headerType> <jar>target/your-app.jar</jar> <outfile>dist/YourApp.exe</outfile> <errTitle>YourApp 启动失败</errTitle> <icon>src/main/resources/app.ico</icon> <singleInstance> <mutexName>YourAppMutex</mutexName> </singleInstance> <jre> <path>bundled/jre</path> <minVersion>1.8.0</minVersion> <maxVersion></maxVersion> <initialHeapSize>128</initialHeapSize> <maxHeapSize>1024</maxHeapSize> <opt>%JAVA_OPTS%</opt> <opt>-Dfile.encoding=UTF-8</opt> </jre> <versionInfo> <fileVersion>1.0.0.0</fileVersion> <txtFileVersion>1.0.0</txtFileVersion> <fileDescription>YourApp Desktop Client</fileDescription> <productName>YourApp</productName> <productVersion>1.0.0</productVersion> <companyName>YourCompany</companyName> </versionInfo> </launch4jConfig>其中headerType有两个可选值，gui表示窗口程序，不会弹出黑色控制台；console则会伴随一个命令行窗口，适合需要看System.out输出的诊断工具。我给自己排查问题用的工具会故意配置成console，方便直接看到日志，正式发给用户的必须用gui。
4.2 命令行构建与Maven集成
有了XML文件，命令行构建就很简单了：
launch4j.exe launch4j.xml在Windows下把launch4j的安装目录加入PATH，然后执行这条命令，它就会读取配置并生成exe。如果想集成到Maven生命周期里，可以用com.akathist.maven.plugins.launch4j这个插件，在pom.xml里指定配置文件路径，执行mvn package时自动完成打包。我自己更喜欢在Jenkins流水线里直接调命令行，因为可控性最强，而且能随时在构建日志里看到launch4j自己的输出信息，比如“wrap jar”过程提示，方便排查问题。
这里再提醒一个版本细节：launch4j有3.x版本，官网提供的Windows版本分为32位和64位，下载时看清楚。64位版本可以处理更大的内存配置和更快的打包速度，但有些老插件是基于32位版本开发的，如果你用老版本Maven插件，得匹配对应的launch4j主程序，否则会出现“cannot create process”或配置读取异常。我遇到过的最诡异的问题就是插件下载launch4j时版本不一致，导致打出的exe双击没反应，最后手动指定了本地launch4j路径才解决。
5. 亲测踩坑记录：常见报错与排查经验
5.1 症状速查表
如果你也是第一次用launch4j，下面这些场景我全都遇到过，整理成一张表方便你对照：
| 现象 | 原因 | 解决办法 |
|---|---|---|
| 双击exe弹出“A suitable JRE was not found” | 目标机没有装JRE，或JRE版本低于minVersion | 目标机装JRE，或用捆绑模式携带jre目录 |
| exe启动后黑框闪一下就消失 | 你的程序启动即抛异常，headerType设为gui时看不到输出 | 临时改成console模式，或先命令行java -jar验证 |
| 中文日志乱码 | 没有设置-Dfile.encoding=UTF-8 | JRE设置页JVM options里加上编码参数 |
| 杀毒软件报毒或拦截 | exe壳加自解压行为容易被误报 | 用代码签名证书签名，或更换图标资源再做一次 |
| 提示“Could not find or load main class” | jar的manifest里主类配置不对 | 重新检查maven-shade-plugin的Main-Class配置 |
| 64位机器上运行报错找不到dll | Runtime bits指定错误 | 确认JNI依赖的dll位数，设置对应Runtime bits |
| exe生成失败，提示输出文件被占用 | outfile路径被程序或杀毒软件锁住 | 关闭占用程序，或换个输出目录再试 |
| JVM崩溃，内存不足异常 | maxHeapSize设置过大或过小 | 先按目标机器内存调整，建议峰值加50%余量 |
5.2 最容易钻牛角尖的细节
再说三个我用了几次之后才彻底弄明白的细节。第一个是JRE捆绑路径问题。XML里<path>bundled/jre</path>这个配置是相对于exe所在目录的。你把exe放到了dist/，那就得把整个jre文件夹复制到dist/bundled/jre。很多人只打包了exe，忘了一起拷贝jre目录，结果在没装Java的机器上依旧报“A suitable JRE was not found”。验证捆绑是否成功有个土办法：拷到一台纯净虚拟机里直接运行，别在自己开发机上测，因为开发机上有JDK，会掩盖问题。
第二个是启动路径问题。Java程序里如果用new File("config.ini")这种相对路径写法，工作目录是exe所在的目录还是系统目录，很多新手分不清。launch4j启动Java时的当前目录继承自exe的启动位置，正常情况下你是双击exe的，工作目录就是exe所在目录。但如果你从命令行用绝对路径去执行exe，工作目录可能就是命令行当前目录了。在程序里我建议始终用System.getProperty("user.dir")或者通过ProtectionDomain获取jar真实路径来定位资源，不要依赖相对路径。
第三个是版本信息页对打开exe属性的影响。在launch4j的Version Info页里填了公司名、产品版本之后，用户在资源管理器里右键exe属性，能看到详细版本信息，这是专业感的重要来源。我见过不少工具exe右键属性一片空白，一看就是没填版本信息。fileVersion格式必须是x.x.x.x四段，txtFileVersion可以写自由文本，两者的内容要一致，否则资源管理器的“版本”页签可能不显示。
6. 进阶玩法：捆绑JRE，让用户彻底不用装Java
6.1 为什么选择捆绑而不是依赖系统JRE
前文多数场景都是“目标机已装JRE，launch4j帮你找它”。但面对政企客户或者普通互联网用户时，让对方装一个几百兆的JDK再运行你的小工具，接受度很低。捆绑JRE的意思是：把你的程序需要的Java运行环境直接放在exe旁边的目录里，launch4j的壳优先使用这个目录下的JRE，找不到再退回系统JRE。这样你的分发目录多出100~200MB，但换来了“免安装、免配置、双击即用”的体验，对于内部管理系统、工业控制软件这类场景非常值得。
6.2 手动捆绑的具体操作步骤
我一般这么操作：先找一个合适的JRE版本的压缩包，推荐用OpenJDK的jre版本，体积比完整JDK小很多。然后把文件夹解压后重命名为jre，放到exe的同级目录下。再用前面提到的XML配置加一行：
<jre> <path>jre</path> <minVersion>1.8.0</minVersion> <maxVersion></maxVersion> </jre>这行的执行逻辑是：launch4j会优先检查jre这个相对目录是否有可用的java.exe，版本在minVersion到maxVersion范围内就用它，否则再去系统PATH中搜索JRE。这里有个坑：你捆绑的JRE是64位的，你的exe如果配置Runtime bits为32位，shell还是不会用它，反而去找系统里的32位JRE。捆绑时要保证JRE架构和Runtime bits设置一致。
实际上我在自己开源的几个小工具里，最终是用jlink裁剪了一套精简运行时，再配合launch4j打包，整个目录从200MB压到了50MB左右。思路是先jlink --add-modules只保留用到的那些Java模块，生成一个精简jre，然后用launch4j的捆绑逻辑指向它。如果你也感兴趣，后续我可以单独写一篇怎么用jlink裁剪运行时、怎么跟launch4j结合。这个组合解决了我遇到的90%的“用户电脑环境太乱”问题。
7. 我最终沉淀下来的工作流
用launch4j也有小两年了，我现在每次给新项目做Windows端分发，基本固定走下面这套流程：先确认jar能被java -jar启动，然后用launch4j图形界面跑一遍配置，确认图标、内存参数、版本信息都没问题，把配置保存成XML并提交到代码库，之后所有发版都走命令行脚本。脚本里固定做三件事：重新打jar、调用launch4j生成exe、把exe连同必要的资源和捆绑jre一起复制到发布目录。这样每次发版都稳定，不存在“我昨天怎么打包来着”的问题。
最后再分享一个小技巧：打包完成后，可以用资源编辑器打开exe看一眼图标和版本信息是否正
