本文详解 Maven 中 maven-shade-plugin 未生效的典型原因：插件被错误置于 块内，导致构建时完全静默；提供精简、可运行的配置模板，并说明验证方法与关键注意事项。
本文详解 maven 中 `maven-shade-plugin` 未生效的典型原因：插件被错误置于 `
在使用 Maven 构建可执行 Fat Jar（即包含全部依赖与主类声明的单体 JAR）时，maven-shade-plugin 是业界首选——它不仅支持依赖打包，还提供类重定位（relocation）、资源合并、冲突处理等高级能力。但大量开发者会遇到一个“无声失败”问题：执行 mvn clean package 后，输出的仍是普通 JAR（由 maven-jar-plugin 生成），控制台日志中甚至找不到 shade 的任何执行痕迹，且生成的 JAR 既无 Main-Class 入口，也不含第三方依赖（如示例中的 gnu.getopt）。
根本原因在于 Maven 的配置作用域误解：
仅用于集中声明插件的默认版本与配置模板，它本身不触发插件执行，也不绑定到生命周期阶段； - 真正启用插件并使其参与构建流程，必须将
声明置于 （即顶层插件块）中。
在你的 pom.xml 中，maven-shade-plugin 被包裹在
<build><pluginmanagement><plugins><plugin><groupid>org.apache.maven.plugins</groupid><artifactid>maven-shade-plugin</artifactid><version>3.4.1</version><!-- ... execution & configuration --></plugin></plugins></pluginmanagement></build>
这相当于“只写了说明书，没按开关”——插件配置存在，但从未被激活。Maven 默认仍调用 maven-jar-plugin:jar（见日志中 maven-jar-plugin:2.4:jar (default-jar)），因此生成的是空依赖、无 MANIFEST 的标准 JAR。
✅ 正确配置方式（精简可运行版）：
将
<build><plugins><plugin><groupid>org.apache.maven.plugins</groupid><artifactid>maven-shade-plugin</artifactid><version>3.4.1</version><executions><execution><phase>package</phase><goals><goal>shade</goal></goals><configuration><transformers><transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer"><mainclass>org.example.Hello</mainclass></transformer></transformers><!-- 关键：禁用 dependency-reduced pom，避免干扰 --><createdependencyreducedpom>false</createdependencyreducedpom><!-- 可选：重命名输出文件，避免与原始 jar 冲突 --><shadedartifactattached>true</shadedartifactattached><shadedclassifiername>fat</shadedclassifiername></configuration></execution></executions></plugin></plugins></build>
✅ 效果验证方法：
- 执行 mvn clean package -X | grep -i "shade"，应看到类似：
Executing org.apache.maven.plugins:maven-shade-plugin:3.4.1:shade- 检查 target/ 目录：除 hello-fat-jar-0.1-SNAPSHOT.jar 外，还会生成 hello-fat-jar-0.1-SNAPSHOT-fat.jar（因启用了 shadedArtifactAttached）；
- 运行 jar -tf target/hello-fat-jar-0.1-SNAPSHOT-fat.jar | head -20，可见 gnu/getopt/ 包路径及大量依赖类；
- 运行 java -jar target/hello-fat-jar-0.1-SNAPSHOT-fat.jar -x，应输出 Hello X! 和 Goodbye。
⚠️ 关键注意事项：
-
勿混用
与 ：多模块项目中，若需统一管理插件版本，应在父 POM 的中声明版本，再于子模块 中仅声明 groupId/artifactId/goals（无需重复 version）； - 避免 MANIFEST 冲突：若同时配置了 maven-jar-plugin，其 MANIFEST 可能覆盖 Shade 的设置，建议移除或显式禁用；
- 依赖冲突处理：当多个依赖含同名资源（如 META-INF/services/*），需添加 ServicesResourceTransformer；
- Java 9+ 模块兼容性：若项目使用模块系统（module-info.java），Shade 不支持自动迁移模块描述符，建议结合 jlink 或改用 jpackage。
最终，一个最小可行的 Fat Jar 构建流程只需三步：
- 将 maven-shade-plugin 正确声明于
； - 配置 ManifestResourceTransformer 指定 mainClass；
- 执行 mvn clean package 并验证输出 JAR 的内容与可执行性。
至此，你已掌握 Maven Shade 插件的核心实践逻辑——不是配置越复杂越好，而是理解作用域、生命周期与插件职责边界，方能一次构建，稳定交付。
