本文详解为何 maven-shade-plugin 未生效的根本原因——误将插件声明置于 <pluginManagement> 中，而非实际启用的 <plugins> 节点，并提供完整、可运行的配置示例与关键注意事项。
本文详解为何 `maven-shade-plugin` 未生效的根本原因——误将插件声明置于 `
在使用 Maven 构建可执行的“Fat JAR”（即包含所有依赖的单体 JAR）时，maven-shade-plugin 是最常用且功能强大的选择。但许多开发者会遇到一个典型问题：执行 mvn package 后，输出的仍是普通 JAR（由 maven-jar-plugin 生成），而非预期的 shaded JAR——控制台日志甚至显示 maven-jar-plugin:2.4:jar (default-jar) 被触发，而 shade 插件完全静默。
根本原因并非插件版本冲突或生命周期绑定错误，而是 Maven 的配置作用域误解：<pluginManagement> 仅用于集中声明插件的默认配置和版本，它本身不会触发插件执行；真正启用插件并参与构建流程，必须将其声明移至 <build><plugins>（即项目级插件配置块）中。
以下是以 simple-client 模块为例的正确配置方式（已修正原始问题）：
<build>
<finalName>Server</finalName>
<!-- ✅ 正确位置：plugins → 实际启用插件 -->
<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>com.firstproject.myapp.AppServer</mainClass>
</transformer>
</transformers>
<minimizeJar>false</minimizeJar>
<createDependencyReducedPom>false</createDependencyReducedPom>
<dependencyReducedPomLocation>
${java.io.tmpdir}/dependency-reduced-pom.xml
</dependencyReducedPomLocation>
<relocations>
<relocation>
<pattern>com.firstproject.myapp</pattern>
<shadedPattern>hidden.coyote</shadedPattern>
</relocation>
</relocations>
</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 的日志；生成的 JAR 文件大小显著增大（含依赖），且可通过 java -jar Server.jar 直接运行。
关键注意事项：
- ✅ 勿混淆 <pluginManagement> 与 <plugins>：前者是“模板”，后者是“实例”。多模块项目中，常在父 POM 的 <pluginManagement> 中统一管理 shade 插件版本，再在子模块 <plugins> 中显式引用（无需重复写 <version> 和 <configuration>）；
- ✅ 确保 <phase> 与 <goal> 匹配：<phase>package</phase> + <goal>shade</goal> 是标准组合，覆盖默认 jar 阶段输出；
- ⚠️ 避免 maven-jar-plugin 干扰：如需彻底禁用默认 JAR 生成（仅保留 shaded JAR），可在同一 <plugins> 块中添加 maven-jar-plugin 并设 <skip>true</skip>，但通常非必需；
- ? finalName 影响输出文件名：上述配置生成 Server.jar，而非默认的 simple-client-1.0-SNAPSHOT.jar，便于部署识别。
总结：Maven 构建逻辑严格遵循配置层级与作用域规则。解决 “Shade 插件不执行” 问题，核心在于理解 <pluginManagement> 的声明式语义，并将执行逻辑落地到 <plugins>。一次正确的配置迁移，即可让 Fat JAR 构建稳定可靠。
