从Gradle3.2.1升级到6.8.1构建报JavaLibrary类NoClassDefFoundError

问题基本信息 #

• 升级路径：将项目使用的Gradle版本从3.2.1直接升级至6.8.1
• 运行环境：MacOS 10.15.7、JVM 15.0.1
• 触发场景：执行项目构建任务时持续失败

核心异常表现 #

• 最外层抛出异常类型：com.google.common.util.concurrent.ExecutionError
• 底层根因异常：java.lang.NoClassDefFoundError，缺失类为org/gradle/api/internal/java/JavaLibrary
• 堆栈定位异常触发节点：Shadow插件应用执行流程中

已完成的前置排查操作 #

• 执行gradle -version命令核验，确认当前环境实际运行的Gradle版本为6.8.1，无版本错配
• 对照官方兼容要求全量核对项目依赖版本，未发现依赖层面的兼容偏差
• 尝试迁移本地Gradle缓存至独立无权限限制的目录，问题未得到缓解
• 全量核验wrapper配置文件，未发现3.2.*旧版本的残留指定配置项

根因定位与解决方案 #

• 核心根因：项目引入的Shadow插件版本与Gradle 6.8.1存在根本性不兼容
  适配Gradle 3.x-4.x的旧版Shadow插件（2.0.4及更早版本）硬编码依赖Gradle内部APIorg.gradle.api.internal.java.JavaLibrary，该内部类从Gradle 5.0版本开始已被重构移除。当旧版Shadow插件被加载到Gradle 6.8.1运行时环境时，就会触发类加载缺失错误；由于插件配置过程是通过Guava并发工具执行的，这类异常会被外层包装为ExecutionError，与观察到的堆栈表现完全匹配。
• 可落地解决步骤：
  1. 定位build.gradle中Shadow插件的引入配置，将旧版2.x系列Shadow插件替换为适配Gradle 6.8.1的兼容版本（6.1.0及以上版本）
  2. 替换配置后执行./gradlew --refresh-dependencies clean build，强制刷新本地缓存中的插件依赖，避免旧版本插件包被重复加载
  3. 确认Gradle启动参数无自定义类加载隔离配置，避免正常类加载路径被阻断

内容的提问来源于stack exchange，提问作者Explorer