如何正确选择 Maven 中需要 Shade 的依赖包

maven shade 插件并非默认必需，仅在特定场景（如插件开发、类加载隔离）下才需谨慎使用；判断是否 shade 及选择哪些包，应优先通过依赖调解、版本统一和精简依赖来解决冲突， shade 应是最后手段。

在构建可分发的 Java 应用（尤其是插件型 JAR，如 Bukkit/Spigot 插件、Jenkins 插件或 Fabric Loader 模组）时，“是否 Shade”以及“Shade 哪些包”常令人困惑。核心原则是：Shade 不是常规操作，而是应对特定类加载冲突的防御性策略。

✅ 何时真正需要 Shade？

• 运行环境不可控：你的 JAR 作为插件被加载到第三方宿主（如 Minecraft 服务端、Jenkins、Eclipse 插件平台），而宿主或其他插件可能已加载了同名但不同版本的依赖（如 guava, gson, slf4j），导致 LinkageError 或 NoSuchMethodError。
• 你无法控制宿主的 classpath：此时，将关键依赖内嵌并重命名（即 Shade + Relocation）可实现类路径隔离。
• 你发布的是“瘦插件”（thin plugin）：自身代码极简，重度依赖外部库，且这些库与宿主生态存在版本不兼容风险。

❌ 何时 不应 盲目 Shade？

• 构建普通独立应用（java -jar app.jar）：应优先使用 maven-assembly-plugin 或 spring-boot-maven-plugin 打 fat jar，而非 Shade —— 后者主要为重定位设计，非单纯打包。
• 依赖冲突可通过 解决：例如，多个传递依赖引入了不同版本的 commons-collections4，可在 pom.xml 中统一声明：

  
    
      org.apache.commons
      commons-collections4
   
   4.4
    
  

• 可通过 exclusions 精简依赖树：移除冗余或冲突的传递依赖：

  com.example
  problematic-lib
  
    
      com.google.guava
      guava
    
  

? 如何确定“该 Shade 哪个包”？（无文档时的实操方法）

当官方未明确建议 relocation 包名时，按以下步骤排查：

1. 分析冲突根源：运行时抛出 ClassNotFoundException 或 NoClassDefFoundError 时，记录完整类名（如 com.google.common.collect.ImmutableList）；
2. 定位所属依赖：执行 mvn dependency:tree -Dverbose | grep -A5 -B5 "guava"，确认该类来自哪个 artifact；
3. 检查其顶层包结构：下载对应 JAR，用 jar -tf xxx.jar | head -20 查看根目录下的 package 前缀（如 com/google/common/ → pattern 应为 com.google）；
4. 最小化 relocation 范围：仅 relocate 实际冲突的包，而非整个依赖。例如：

   
     com.google.common.
     ${shade.base}.guava.
   

   注意末尾的 .，避免误匹配 com.google.commoner 等无关包。

⚠️ 重要注意事项

• 避免过度 Shade：Shading org.slf4j 或 javax.annotation 等 SPI/契约类可能导致日志失效或注解处理器异常；
• 测试必须覆盖运行时环境：仅在 IDE 或 mvn exec:java 中通过不代表插件真实可用——务必在目标平台（如 Spigot 服务器）中验证；
• 命名需唯一且有意义：推荐格式 ${project.groupId}.shaded，例如 com.myapp.shaded，避免与其他插件 Shade 冲突；
• 考虑替代方案：对日志、JSON、HTTP 等通用能力，优先选用宿主已提供的 API（如 Spigot 的 YamlConfiguration、Jenkins 的 TaskListener），减少依赖引入。

总之，Shade 是一把精准手术刀，不是万能胶。先诊断、再调解、最后隔离——这才是稳健交付插件或嵌入式模块的正确路径。