Gradle 8.0升级：子项目应用java-library插件失败报错

架构老林

2026-7-27

Gradle 8.0升级时java-library插件应用失败的解决方法

问题重现

根项目build.gradle中配置了子项目统一应用java-library插件：

...
subprojects {
    apply plugin: 'java-library'
    ...
}
...

升级至Gradle 8.0时出现以下错误：

Failed to apply plugin class 'org.gradle.api.plugins.JavaPlugin'.
No signature of method: static org.gradle.api.plugins.internal.JvmPluginsHelper.configureDocumentationVariantWithArtifact() is applicable for argument types: (String, null, String, EmptyList, String, org.gradle.api.internal.file.DefaultSourceDirectorySet_Decorated...) values: [sourcesElements, null, sources, [], sourceJar, main source, ...]

原因分析

该错误是因为Gradle 8.0对内部API org.gradle.api.plugins.internal.JvmPluginsHelper的方法签名做了破坏性变更，而你的构建脚本或依赖的第三方插件中存在直接调用该内部API的代码，导致方法匹配失败。内部API本身不对外公开，Gradle版本升级时随时可能变更，因此不建议直接使用。

解决方案

替换内部API调用为官方公开API
如果脚本中手动配置了源码Jar、文档Jar等，改用Gradle java-library插件提供的标准方式：
- Gradle 7.0+推荐写法（配置源码Jar）：
```
java {
    withSourcesJar()
}
```
- 兼容旧版的写法：
```
task sourceJar(type: Jar) {
    from sourceSets.main.allJava
    archiveClassifier = 'sources'
}

artifacts {
    archives sourceJar
}
```
升级第三方插件到兼容Gradle 8.0的版本
检查项目中使用的所有第三方插件（如Spring Boot、Android、Jacoco等），将其版本更新至官方声明支持Gradle 8.0的最新版本，旧版本插件可能依赖过时内部API引发冲突。
统一插件版本
确保根项目和所有子项目使用的Gradle插件版本保持一致，避免跨版本插件混合使用导致兼容性问题。