Maven Shade 插件配置生成 Fat Jar 方法

本文直击 Maven 开发者构建 Fat Jar 时最常遭遇的“静默失败”痛点——maven-shade-plugin 因误配在 `` 中而完全不生效，导致生成的 JAR 缺乏依赖和主类入口、无法直接运行；文章不仅一针见血指出根源在于配置作用域与生命周期绑定的混淆，更提供经过验证的极简可运行配置模板、四步精准验证法（含调试日志过滤、JAR 内容检查、命令行执行），并附上多模块管理、MANIFEST 冲突规避、资源合并、Java 模块兼容等关键实战注意事项，助你彻底告别无效配置，用最清晰的理解实现一次构建、开箱即用的可执行 Fat Jar。

本文详解 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。

✅ 正确配置方式（精简可运行版）：
将 移出 ，直接置于 下，并确保 绑定到 package 阶段：

<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 构建流程只需三步：

1. 将 maven-shade-plugin 正确声明于 ；
2. 配置 ManifestResourceTransformer 指定 mainClass；
3. 执行 mvn clean package 并验证输出 JAR 的内容与可执行性。

至此，你已掌握 Maven Shade 插件的核心实践逻辑——不是配置越复杂越好，而是理解作用域、生命周期与插件职责边界，方能一次构建，稳定交付。

好了，本文到此结束，带大家了解了《Maven Shade 插件配置生成 Fat Jar 方法》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！