Gradle报错Plugin with id ‘maven‘ not found？迁移maven-publish全攻略

先别急着一遍遍 clean、重启、删缓存——org.gradle.api.plugins.UnknownPluginException: Plugin with id maven这条报错我这两年帮朋友排查项目时见过太多次了。它不是环境坏了也不是网络断了而是你的构建脚本还在用一套Gradle官方已经淘汰的旧写法。简单说你让Gradle加载一个叫maven的插件但当前Gradle版本里根本没有这个插件。这事在Gradle 7.x以上几乎是必然复现的尤其是从Eclipse时代迁移过来、或者从老博客复制过构建脚本的项目。下面我把原因、迁移方案、实际操作和踩坑点一次讲清楚照着改基本几分钟就能让项目重新编译跑起来。1. 报错到底在说什么1.1 先看懂这行异常信息UnknownPluginException是Gradle在解析插件时抛出的通用异常完整信息通常会带一个not found后缀类似这样* What went wrong: Plugin [id: maven] was not found in any of the following sources: - Gradle Core Plugins (plugin is not in org.gradle namespace) - Plugin Repositories (could not resolve plugin artifact maven:maven.gradle.plugin)核心就是最后那句Gradle在“插件核心列表”和“插件仓库”里都找不到 id 为maven的插件。这个报错跟Java代码、依赖冲突都没关系它发生在构建初始化阶段脚本一执行到apply plugin: maven就挂了。1.2 Gradle插件的两种身份想理解这个报错得先搞清楚Gradle插件是怎么被加载的。Gradle里的插件有两种主要来源核心插件Core Plugin随Gradle发行版一起发布比如java、application、android系列插件不需要额外声明依赖直接apply plugin: java就能用。二进制插件Binary Plugin由第三方打包成jar发布到Maven仓库比如com.android.application必须在buildscript或plugins块里声明classpath依赖Gradle才能从仓库下载。以前maven插件属于“核心插件”里的老成员配合uploadArchives任务把项目打包上传到Maven仓库。但后来Gradle官方推出了功能更完整的maven-publish插件旧的maven插件被标记为过时并在Gradle 7.0版本里正式移除了。所以你现在项目里写apply plugin: mavenGradle 6还能勉强识别Gradle 7以上直接告诉你查无此插件你自己看着办。1.3 为什么以前能用现在突然报错这往往是项目升级Gradle版本后爆出来的问题。常见场景有三个老项目从Gradle 5.x或6.x升级到Gradle 7.x/8.x构建脚本没同步更新。从网上下载的旧教程Demo项目的gradle-wrapper.properties指向了新版本Gradle但build.gradle还是十年前的写法。Android Studio自动升级了内置Gradle版本低版本项目直接被新构建器扫出历史遗留问题。还有一部分场景是Flutter创建的Android工程早期模板里也用过类似写法。新版Flutter模板已经改成id com.android.library这类现代语法了但老项目升级编译SDK时同样可能撞上这堵墙。2. 最直接的解法从 maven 迁移到 maven-publish2.1 老配置通常长什么样如果你用的是apply plugin: maven大概率后面还挂着一套uploadArchives配置类似这样apply plugin: maven uploadArchives { repositories { mavenDeployer { repository(url: http://192.168.1.100:8081/repository/libs-release/) { authentication(userName: admin, password: admin123) } pom.groupId com.example pom.artifactId lib-core pom.version 1.0.0 } } }这段配置在Gradle 6时代还能跑上传时执行./gradlew uploadArchives。升级到Gradle 7之后不仅apply plugin: maven找不到uploadArchives任务也从任务列表里消失了。2.2 新配置应该怎么改把apply plugin: maven整段替换成apply plugin: maven-publish然后用publishing块重写发布逻辑。这里先给一个最简的Java/Kotlin库版本apply plugin: java-library apply plugin: maven-publish publishing { publications { mavenJava(MavenPublication) { from components.java groupId com.example artifactId lib-core version 1.0.0 } } repositories { maven { name local url uri(${rootProject.buildDir}/repo) } maven { name remote url http://192.168.1.100:8081/repository/libs-release/ credentials { username admin password admin123 } } } }如果你只是想把库发布到本地Maven仓库也就是~/.m2/repository不需要写仓库地址直接跑./gradlew publishToMavenLocalGradle会自动把产物装进本机的Maven本地仓库别的工程里配置mavenLocal()就能引用。2.3 Android项目发布AAR的完整写法Android Library项目比纯Java库多一个坑from components.java直接会找不到组件。Android插件注册的是components.release这些Android变体组件需要指定变体。实际项目中我推荐这样写apply plugin: com.android.library apply plugin: maven-publish android { namespace com.example.libcore compileSdk 34 defaultConfig { minSdk 21 targetSdk 34 versionCode 1 versionName 1.0.0 } } publishing { publications { release(MavenPublication) { groupId com.example artifactId lib-core version 1.0.0 // Android Library组件需要从 afterEvaluate 里取 afterEvaluate { from components.release } } } repositories { maven { name local url uri(${rootProject.buildDir}/repo) } } }这里必须把from components.release包在afterEvaluate里因为Android变体组件是在项目配置阶段结束后才注册的直接写在publishing外层经常报component release not found。这个问题我踩过好几次如果你把from components.release放在外面而且没有用afterEvaluate包裹大概率会看见这条报错。执行发布命令./gradlew publishReleasePublicationToLocalRepository任务名是publish 发布件名称(大写开头) PublicationTo 仓库名称 Repository。上面配置的发布件叫release仓库叫local所以任务名就是publishReleasePublicationToLocalRepository。发布完成后产物在项目根目录/build/repo/com/example/lib-core/1.0.0/下里面有AAR文件、POM文件以及校验用的MD5/SHA1文件。另一个工程引用时在repositories里加一行maven { url uri(${rootProject.buildDir}/repo) }再正常implementation com.example:lib-core:1.0.0就能引到了。3. 还有一个可能你用的是旧版第三方android-maven插件3.1 怎么判断是这个插件并不是所有maven报错都是Gradle内置插件引起的。一部分老Android项目会在根工程的buildscript里声明一个第三方classpath依赖然后再apply一个带公司名的插件buildscript { repositories { mavenCentral() jcenter() } dependencies { classpath com.github.dcendev:android-maven-gradle-plugin:2.1 } } apply plugin: com.github.dcendev.android-maven这个插件的groupId是com.github.dcendev老版本叫android-maven-gradle-plugin配合老Gradle使用。它同样实现了类似uploadArchives的功能。如果你的报错信息里出现的是Plugin with id com.github.dcendev.android-maven而不是Plugin with id maven那就是这类情况。3.2 迁移到新版坐标这个插件其实有对应的新版本作者把Gradle 7/8兼容版本换了新的坐标和插件名buildscript { repositories { mavenCentral() } dependencies { classpath com.github.dcendev:android-maven-publish:3.6.2 } } apply plugin: com.github.dcendev.android-maven-publish新版插件同样基于Gradle官方的maven-publish实现所以改完之后也可以直接使用publish相关的仓库配置和任务。如果你的代码里还挂着一套老式的uploadArchives配置最好还是按照第2节的方式重写成publishing块别留两套逻辑在项目里后续维护很痛苦。3.3 排查插件加载路径遇到这种第三方插件解析失败先确认buildscript里的仓库有没有正确配置。之前有个朋友的项目报UnknownPluginException我远程看他的build.gradle发现buildscript.repositories里只有jcenter()——jcenter早已停止服务插件jar根本下载不下来Gradle自然就说未找到插件。这类排查顺序我建议固定下来先看buildscript.dependencies里有没有对应的classpath声明。没有就去补上声明了还报错那大概率是仓库源无法访问。把repositories换成阿里云或Maven Central再重试。4. 配套修复Gradle版本与依赖仓库整理报错解决不等于项目构建就畅通无阻。很多项目升级到新Gradle版本之后除了maven插件还会冒出一连串别的插件解析问题、依赖下载超时问题。所以建议一次性把Gradle版本、AGP版本、仓库镜像三个配套项一起理顺。4.1 Gradle版本和AGP兼容关系Android Gradle PluginAGP和Gradle版本之间是强绑定的。AGP版本太老配新Gradle或者AGP太新配老Gradle都会出各种奇怪问题。这里放一张我整理的基础兼容表AGP版本最低Gradle版本备注3.5.x5.4.1老项目常见3.6.x5.6.4老项目常见4.0.x6.1.1老项目常见4.1.x6.5部分老项目4.2.x6.7.1迁移分水岭7.0.x7.0需要JDK 117.4.x7.5当前较稳8.0.x8.0需要JDK 178.5.x8.7新项目推荐升级项目的时候尽量保持AGP和Gradle在表格对应区间内。比如你想用Gradle 8.5AGP至少要在8.x以上。否则你刚解决了maven插件问题又会在AGP的API调用上报一个NoSuchMethodError或者Unsupported class file major version之类的怪错。4.2 配置国内镜像解决依赖拉不下来国内开发者常见的第二个痛点就是Gradle下载发行版慢以及依赖仓库访问不稳定。关于“Android Studio每次新建项目都要下载Gradle”这个问题核心在gradle-wrapper.properties里的distributionUrldistributionUrlhttps\://services.gradle.org/distributions/gradle-8.5-bin.zip可以把地址替换成腾讯镜像下载速度快很多distributionUrlhttps\://mirrors.cloud.tencent.com/gradle/gradle-8.5-bin.zip镜像包名要保持一致只是域名路径不同。改完之后重新打开Android Studio如果提示gradle下载选那个文件自己重新加载就行。依赖仓库镜像则建议统一用阿里云。根工程或settings.gradle里参考下面这个配置pluginManagement { repositories { maven { url https://maven.aliyun.com/repository/gradle-plugin } maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/google } gradlePluginPortal() google() mavenCentral() } } dependencyResolutionManagement { repositories { maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/gradle-plugin } google() mavenCentral() } }把阿里云仓库放在最前面Gradle会优先走阿里云失败再走后面的google和mavenCentral。这个顺序很关键如果放反了还是会先卡在Google仓库的超时上。4.3 清理Gradle缓存和重试改完配置如果还是报错不要马上怀疑配置写错先清理一遍Gradle缓存cd 项目目录 ./gradlew --stop rm -rf ~/.gradle/caches/ ~/.gradle/wrapper/dists/然后重新执行./gradlew helphelp这个任务只是加载构建配置不编译代码如果这一步能过说明插件解析、仓库配置都没问题了。再用它来做验证非常快比直接点编译按钮省心。5. 常见问题与排查实录5.1 报错速查表这部分我把实际排查中遇到过的高频情况整理成表格方便你对着查报错信息主要原因处理方式Plugin with id maven not foundGradle 7移除了旧maven插件改用maven-publish参照第2节Plugin with id com.github.dcendev.android-maven not found旧版第三方插件没有声明classpath换成com.github.dcendev:android-maven-publishCould not find plugin maven插件仓库没有这个jar配置阿里云gradle-plugin镜像Component release not foundAndroid组件未注册或afterEvaluate缺失把from components.release包进afterEvaluateTask uploadArchives not founduploadArchives已被更新版本移除改用publish相关任务Could not install Gradle distribution from ...wrapper下载超时distributionUrl换成腾讯镜像Deprecated Gradle features were used构建脚本用旧API按提示加--warning-mode all看具体告警项逐条替换5.2 上传之后其他模块怎么引用本地仓库有些团队习惯在项目里维护一个私有组件库把公共模块发布到本地Maven仓库然后给其他工程用。发布完成之后引用方需要在settings.gradle的dependencyResolutionManagement里加上仓库地址dependencyResolutionManagement { repositories { maven { name local-repo url uri(D:/workspace/shared-maven-repo) // 自定义共享目录 } } }然后再加依赖implementation com.example:lib-core:1.0.0这里有个必须记住的细节Gradle在Gradle 7之后默认启用了dependencyResolutionManagement管理仓库如果你引用的库不在任何已声明仓库里即使本机~/.m2里有货也不会自动扫到。必须显式写上mavenLocal()或者对应路径否则就是标准的Could not find com.example:lib-core:1.0.0。5.3 个人踩坑心得这类报错在网上搜一圈很多人会告诉你“去Gradle官网下载离线包”“重新装Android Studio”但这些都属于绕路操作。离线包和Gradle版本不匹配反而会引发新的兼容问题。我实际处理这个问题很少需要动Android Studio本身基本就是改脚本、清缓存两步走。截一个最常见的误区有的人看到报错就回退Gradle版本把distributionUrl从8.x改回5.x。这确实能让旧maven插件复活但代价是AGP新版本、JDK 17、Android SDK新API全部跟着不兼容属于拆东墙补西墙。除非你就是要维护一个完全冻结的老项目否则强烈建议往maven-publish方向迁移。另外有一个小细节修改完构建脚本后Android Studio偶尔会提示 “Gradle project sync failed”这时候点Try Again不一定管用最好先执行一次我前面说的./gradlew --stop和rm -rf ~/.gradle/caches/再重新Sync。Gradle守护进程会缓存旧脚本状态不清掉它改十遍都像是在跟一个“记仇”的构建器较劲。根据我个人习惯最终的检查顺序是这样的先看报错行指向哪个apply plugin再查Gradle版本然后看buildscript仓库配置最后才去动AGP和依赖。大部分问题都能在这四步里定位完全不需要把整个工程推倒重来。