如何使用 Maven Shade 插件正确构建可执行 Fat Jar

本文详解 Ma ven 中 ma ven-shade-plugin 未生效的根本原因：插件被错误置于 块内，导致其不参与构建生命周期；提供精简、可靠、经验证的配置方案，并说明验证方法与关键注意事项。

应用程序要打包成一个包含全部依赖（比如 gnu.getopt 这类第三方库）、能直接通过 ja va -jar 启动的 Fat Jar（也叫 Uber JAR），ma ven-shade-plugin 几乎是官方钦定的最优解。它不仅负责把依赖一股脑打包进去，连类重定位（relocation）、资源合并、自动写入 MANIFEST.MF 这类活儿也能一并干完。不过，实际项目里大多数人说“配了但没有用”，问题真不在插件本身，而是对 Ma ven 配置作用域的理解出了偏差。

❌ 常见错误：误用

比如你给出的 pom.xml 里，ma ven-shade-plugin 被裹在 标签下面：

                    org.apache.ma ven.plugins        ma ven-shade-plugin                    

这里有必要强调一个区别： 只是用来“集中声明插件的默认版本和配置模板”的，它不能触发任何执行代码。它不绑定生命周期（比如 package 阶段），不参与实际构建流程。所以 Ma ven 最后还是调用默认的 ma ven-jar-plugin（日志里能看到 ma ven-jar-plugin:2.4:jar (default-jar)），生成一个只有自身字节码的普通 JAR —— 这就是为什么你运行 jar tf 看不到 gnu/getopt/ 类，跑 ja va -jar 又报错说 no main manifest attribute。问题根源就在这里。

✅ 正确配置：移至 （项目级启用）

解决办法很简单：把 块直接放到 下面，别放在 里。看配置：

  hello-fat-jar                 org.apache.ma ven.plugins      ma ven-shade-plugin      3.4.1                         package                      shade                                                                          org.example.Hello                                                  false                        false                              

? 如果省略 ，默认命名是 ${artifactId}-${version}；如果你想保留原始 jar，同时再生成一个 fat jar，可以把 设为 true，此时 fat jar 会以 xxx-shaded.jar 命名。

? 验证是否生效

构建完成后，跑一下这条命令，确认插件是否被正常执行：

mvn clean package -X | grep -i "shade"

正常的话，日志里应该能看到：

[DEBUG] Configuring mojo 'org.apache.ma ven.plugins:ma ven-shade-plugin:3.4.1:shade' ...[INFO] --- ma ven-shade-plugin:3.4.1:shade (default) @ hello-fat-jar ---[INFO] Including gnu.getopt:ja va-getopt:jar:1.0.13 in the shaded jar.

输出文件的验证步骤也很直观：

ls target/# 应该能看到 hello-fat-jar-0.1-SNAPSHOT.jar（明显比原 jar 大）jar -tf target/hello-fat-jar-0.1-SNAPSHOT.jar | head -20# 输出里应该包含 gnu/getopt/Getopt.class、META-INF/MANIFEST.MF 等# 检查 MANIFEST 是否写入了 Main-Classunzip -p target/hello-fat-jar-0.1-SNAPSHOT.jar META-INF/MANIFEST.MF# 输出应当包含：Main-Class: org.example.Hello

最后，直接运行看看效果：

ja va -jar target/hello-fat-jar-0.1-SNAPSHOT.jar -x# 预期输出：Hello X! \n Goodbye

⚠️ 注意事项与最佳实践

• 版本兼容性：JDK 17+ 的项目，务必用 ma ven-shade-plugin 3.4.1 及以上版本——老的 2.4.3 对模块化支持不太行；
• 依赖冲突处理：如果多个依赖里包含同名资源（比如 META-INF/services/*），得加上 ServicesResourceTransformer，避免互相覆盖；
• 类重定位（Re-location）：多个依赖中嵌入了不同版本的同一个库（比如 Gua va），可以通过 配置把包路径重命名，避免类名冲突；
• 和 ma ven-assembly-plugin 的区别：Shade 更适合生产环境——它原生支持资源合并策略与类隔离，而 Assembly 更侧重于灵活的归档格式（比如 tar.gz）；
• 多模块项目：Shade 插件一定要配置在具体子模块的 pom.xml 里（比如 simple-server/pom.xml），而不是父 POM 的 中。

一句话总结：能不能构建出可执行的 Fat Jar，关键看配置放对位置—— 是开关， 只是说明书。一次调整到位，以后就不用再为同样的问题折腾了。