刚接手一个新项目拉下代码打开 Android StudioGradle Sync 转了没两圈就甩出一行红字Could not find org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.24。这种报错在 Kotlin 项目里出现的频率极高尤其是在换电脑、换版本、换网络环境之后几乎每个写过 Kotlin 的同学都至少撞上过一两次。它看起来吓人但本质上是一个非常明确的地址找不到问题——Gradle 拿着你给的坐标去仓库里敲门敲了一圈没人应。真正麻烦的地方在于导致没人应的原因有好几种配置写错、仓库没配、版本号对不上、本地缓存脏了、离线模式开着都会呈现出几乎一模一样的错误文本所以很多人第一反应是去删缓存、重启 IDE来回折腾半小时也没解决。这篇文章就是围绕这个报错展开的完整排查与修复手册。我会先说清楚kotlin-gradle-plugin到底是什么、它在构建流程里扮演什么角色再把可能的原因拆成四类逐一分析然后给出一套从确认坐标到验证结果的可复现流程包含镜像仓库配置、离线场景兜底、版本对齐表以及一堆我自己踩过的坑。不管你是刚开始学 Kotlin 的新手还是已经带过几个 Android 项目的开发者只要你的构建脚本里出现了 Kotlin 插件这篇内容都能直接拿去对照使用。1. 先把报错信息本身拆开看1.1 一行错误里其实藏着三个关键信息Could not find org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.24这行字按 Maven 坐标的格式可以切成三段groupId是org.jetbrains.kotlinartifactId是kotlin-gradle-plugin最后那个冒号后面的1.9.24是版本号。这三段合起来就是 Gradle 要去仓库里找的唯一地址。而错误里如果版本号位置显示的是星号比如kotlin-gradle-plugin:*那说明问题出在版本压根没被解析出来而不是版本号写错了——这两种情况的排查方向完全不同。前者意味着 Gradle 明确知道要哪个版本但去的仓库里没有这个版本的文件后者意味着你的构建脚本在依赖声明阶段就没有把版本传进去Gradle 只能拿着一个通配符去问仓库你有没有这个包的任意版本仓库答复我不知道你要哪个版本于是报错。实际项目里星号出现得还挺多常见于版本变量拼写错误、ext属性没定义、libs.versions.toml里的 key 对不上、或者根项目和子项目的插件声明方式混用。另外要注意错误信息前面往往还有一行上下文比如 Could not resolve all files for configuration :app:classpath或者Could not resolve org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.24甚至后面跟着一串Searched in the following locations。那段Searched in the following locations才是真正值钱的东西它会把 Gradle 实际去过的每一个仓库地址列出来。多数人只盯着第一行红字看忽略了下面那一长串结果就是盲目试错。我的习惯是先把这串地址完整看一遍确认里面有没有我期望的仓库如果没有问题基本一眼就能定位。1.2 kotlin-gradle-plugin 在构建流程里的位置很多人对这个包的印象停留在Kotlin 项目要加的一个依赖其实它的角色比这重要得多。Kotlin 代码最终要编译成 JVM 字节码而 Gradle 本身并不认识 Kotlin它只认识一套通用的构建任务模型。kotlin-gradle-plugin就是那个中间人它向 Gradle 注册compileKotlin、kotlinOptions、KotlinCompile任务类型这些扩展点把 Kotlin 编译器的行为包装成 Gradle 能理解的任务。没有它你的.kt文件在 Gradle 眼里就是一堆无意义的文本。这也解释了为什么它必须出现在构建脚本的 classpath 上而不是普通依赖里。用 Groovy DSL 的传统写法是这样的buildscript { repositories { google() mavenCentral() } dependencies { classpath org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.24 } }这段代码的意思是在配置阶段开始之前先把 Kotlin 插件的 jar 包下载下来加载到构建脚本的类加载器里。注意buildscript块里有自己的repositories它和你allprojects里配的仓库是两套东西。这个细节是大量报错的源头——很多人在allprojects里老老实实配了镜像却没意识到buildscript块走的还是默认仓库插件照样下不下来。新版本的 Gradle 更推荐用plugins块加settings.gradle里的pluginManagement// settings.gradle pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } }两种写法定位仓库的路径不一样排查的时候必须分清当前项目用的是哪一套。我在接手别人代码时第一步永远是先看settings.gradle有没有pluginManagement块再看根build.gradle有没有buildscript块两者都有的话说明项目处在迁移中间态最容易出问题。1.3 为什么这个包特别容易找不到对比一下其他依赖会发现kotlin-gradle-plugin的报错率明显偏高原因有这么几个。一是它的发布渠道比较特殊同时存在于 Maven Central 和 Gradle Plugin Portal两个仓库的索引结构不同用plugins {}块解析时要走 plugin marker 机制也就是会先去查org.jetbrains.kotlin.jvm:org.jetbrains.kotlin.jvm.gradle.plugin这个标记包再由它指向真正的实现包中间任何一环断了都会报找不到。二是它和 Kotlin 编译器版本强绑定。你写1.9.24就必须真的有1.9.24这个发行版而且这个版本还必须支持你当前的 Gradle 版本。Kotlin 官方对 Gradle 的支持区间是有限制的太新的 Gradle 配太旧的 Kotlin 插件或者反过来都可能出现解析异常。三是国内网络环境的现实情况。Maven Central 和 Gradle Plugin Portal 的服务器都在境外直连下载大文件时超时、中断的比例不低。一次没下完Gradle 会在缓存目录里留下不完整的记录下次同步时它以为已有缓存直接跳过下载结果加载时失败——表现出的错误文本和仓库里没有几乎一样。这个坑我在早些年遇到过好几次最后发现根本不是配置问题而是缓存里躺着一个 0 字节的 jar。2. 四类根因按概率从高到低排查2.1 仓库声明缺失或写错了作用域这是最常见的一类。典型场景是我配了mavenCentral()但项目用的是plugins {}块而pluginManagement里的仓库列表被我改成了只有公司内网仓库。又或者项目里只有google()和mavenCentral()但某个依赖被发布到了gradlePluginPortal自然就找不到。还有一种更隐蔽的情况仓库配了但配在了错误的位置。Gradle 的仓库作用域有好几层——pluginManagement管插件解析buildscript管构建脚本依赖dependencyResolutionManagement管项目依赖allprojects是给所有子项目加仓库。这四层互不覆盖你在allprojects里加的镜像对buildscript完全无效。我见过一个项目开发同学把阿里云镜像仔仔细细加到了allprojects.repositories里然后抱怨插件还是下不下来就是因为插件走的是buildscript那条路。判断方法很简单看错误信息里Searched in the following locations后面的地址列表。如果列表里全是境外的默认地址说明你的镜像根本没生效如果列表是空的或者只有一两个奇怪的地址说明仓库声明本身就没被执行到。以我的经验这一条能覆盖六成以上的同类报错。2.2 版本号写错或者三方版本互相不兼容版本问题的表现形式有两种。一种是纯粹的手滑比如把1.9.24写成1.9.2、1.9.4这种不存在的版本号或者把kotlin_version变量名拼错导致值变成了空字符串。这种情况下 Gradle 会老老实实去查一个不存在的版本报错文本中版本号是完整的数字看起来很正常但实际上仓库里没有这个发行版。另一种是版本互相打架。Kotlin 插件对 Gradle 版本有明确的兼容区间Android Gradle Plugin 又对 Gradle 版本有自己的要求三者关系可以简化成AGP 决定 Gradle 能用哪个大版本Kotlin 插件决定它能不能在某个 Gradle 版本上跑起来。举个例子如果你的项目用了较新的 Android Gradle Plugin它可能强制要求 Gradle 8.x而项目里声明的 Kotlin 插件版本还停留在比较早的发行版这个组合在某些边角情况下就会出现解析或加载异常。正确做法是把三个版本拉到一个经过验证的组合上不要随便单独升级其中一个。这里我要特别提醒一句不要迷信最新版本一定最好。我在项目里见过把 Kotlin 插件直接拉到最新主版本结果因为语法变更和已有代码不兼容编译期报出一堆莫名其妙的错误最后还得回退。稳定优先是构建配置里最朴素也最有效的原则。2.3 网络中断导致的半吊子缓存这类问题最气人因为它伪装得特别好。Gradle 下载依赖时如果连接中断会在~/.gradle/caches/modules-2/files-2.1/下面创建目录结构但内容不完整。下次构建时 Gradle 检查缓存发现目录存在就认为这个依赖我已经有了直接跳过网络请求。等到真正加载时发现文件读不出来于是抛出解析失败。判断这类问题有一个很直接的信号报错信息里偶尔会夹杂java.net.SocketTimeoutException、Connection reset或者Read timed out这类底层异常。如果你看到这些字样基本可以确定是网络链路的问题而不是配置写错。这时候光改仓库地址没用必须先把脏缓存清掉。缓存目录的位置按平台不同会有差异Linux 和 macOS 下是~/.gradle/caches/Windows 下是C:\Users\你的用户名\.gradle\caches\。要清理某个具体依赖可以直接删对应的 group 目录比如caches/modules-2/files-2.1/org.jetbrains.kotlin/。但更稳妥的做法是保留缓存目录、只加--refresh-dependencies参数跑一次让 Gradle 重新校验。我在实际项目里倾向于后者因为全量删缓存意味着所有依赖重新下载网络不好的时候要等很久。2.4 离线模式与本地环境配置互相干扰Gradle 有一个--offline开关开启后所有依赖都从本地缓存取不再访问网络。这个开关本意是给网络受限环境用的但如果残留配置没清掉就会出现明明有网却怎么都下不下来的情况。Android Studio 的 Gradle 设置面板里有个 Offline work 复选框命令行里也可以加--offline两处都可能被之前的人打开过。另外还有两个容易被忽略的环境项。一个是GRADLE_USER_HOME环境变量如果它被指向了一个空的或者不完整的目录Gradle 会去那里找缓存自然找不到报错和仓库没有一模一样。另一个是gradle.properties里可能存在的代理相关配置如果之前配置过某些网络转发参数而目标服务已经不可用Gradle 会尝试走那条路然后超时。排查时先把这两个地方确认一遍能省下不少时间。3. 一套可以照着做的修复流程3.1 第一步确认你要的坐标和版本到底是什么动手改配置之前先把信息确认清楚这比直接乱试有效得多。打开根目录的build.gradle搜索kotlin看插件是怎么声明的再打开settings.gradle看有没有pluginManagement块如果项目用了版本目录Version Catalog还要去看gradle/libs.versions.toml。[versions] kotlin 1.9.24 [plugins] kotlin-jvm { id org.jetbrains.kotlin.jvm, version.ref kotlin }Version Catalog 的好处是版本集中管理坏处是 key 写错时报错信息会比较绕。我遇到过version.ref指到一个不存在的版本 key结果解析出来的版本号是空报错里就带着星号。所以看到星号第一个要查的就是版本目录文件里的 key 名是否对得上。确认完版本之后去 Maven Central 的官网搜一下这个坐标看对应版本是否真实存在、发布时间是什么时候。这一步花不了两分钟但能排除掉一大半版本号打错了的情况。顺便也能确认这个版本有没有被撤回过——极少数情况下发行版会因为严重问题被下架。3.2 第二步把仓库声明补齐并且补在正确的位置确认坐标没问题之后开始配仓库。如果你的项目能访问外网但速度慢用镜像是最省事的方案。下面是一份我常用的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 { repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS) repositories { maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/google } google() mavenCentral() } }有几个细节必须说清楚。第一镜像地址要放在前面官方地址放在后面兜底。Gradle 是按声明顺序依次查询的镜像靠前意味着优先走镜像镜像没有的包再回落到官方源这样既不丢包又能提速。第二repositoriesMode这个设置很关键PREFER_SETTINGS表示优先用 settings 里声明的仓库FAIL_ON_PROJECT_REPOS更严格会直接禁止子项目自己声明仓库——如果你的项目还在根build.gradle里写allprojects { repositories { ... } }用FAIL_ON_PROJECT_REPOS会直接报错需要同步把那段删掉或改成PREFER_SETTINGS。第三buildscript方式的老项目要在build.gradle里单独配一份buildscript { repositories { maven { url https://maven.aliyun.com/repository/gradle-plugin } maven { url https://maven.aliyun.com/repository/public } google() mavenCentral() } dependencies { classpath org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.24 } }两套配置都写上并不冲突属于稳妥的冗余。等确认构建能跑通之后再考虑精简。注意镜像仓库的地址和路径会随时间调整配置前建议先确认当前可用的地址不要直接复制几年前的旧链接。3.3 第三步清理脏缓存强制重新解析仓库配好之后先别急着相信它生效了。执行下面这条命令让 Gradle 忽略本地缓存、重新走一遍解析./gradlew --refresh-dependencies clean assembleDebugWindows 下把./gradlew换成gradlew.bat即可。--refresh-dependencies的作用是让 Gradle 重新校验所有依赖的元数据包括那些它认为已经在缓存里的包。如果这一步能顺利通过说明问题确实出在缓存或者仓库配置上如果还是报同样的错就要回头看第二步的配置是不是真的生效了。判断配置是否生效有个小技巧在命令后面加上--info或--debug日志里会打印出实际使用的仓库列表。搜索Repository相关的行看看你配的镜像地址在不在里面。如果不方便看日志也可以临时把网络断开再跑一次——如果此时错误信息里出现了更多境外地址的超时提示说明镜像没被用上。3.4 第四步完全离线的环境怎么办有些场景是真的没有外网比如内网构建机、隔离环境。这种情况下有几条路可以走。第一条路是把依赖预先下载好放到本地 Maven 仓库目录里然后在构建脚本里加上mavenLocal()。Gradle 会去~/.m2/repository找包路径结构必须完全符合 Maven 规范org/jetbrains/kotlin/kotlin-gradle-plugin/1.9.24/下面要有 jar 和 pom 文件。这个方法的好处是干净坏处是依赖传递需要自己补齐缺一个就报一次错比较费功夫。第二条路是用公司或团队自建的私有仓库把外部依赖提前同步进去构建时统一指向内网地址。这也是团队协作里最推荐的做法一次配置全员受益还能避免每个人环境不一致带来的差异。第三条路是把整台机器的 Gradle 缓存目录打包复制到目标机器上。这个办法最简单粗暴但要注意缓存目录里的路径包含用户名和哈希值跨平台复制的成功率不稳定Linux 之间相对可靠跨系统基本别指望。如果只是临时断网加--offline参数跑一次也行./gradlew --offline assembleDebug前提是缓存里确实有完整的包。这个方法适合在飞机上或者地铁里改代码的场景但不要长期开着离线模式否则新增依赖时会一直失败。3.5 第五步确认问题真的解决了看到BUILD SUCCESSFUL只是第一步。我的习惯是再做三件事来确认。第一把构建缓存和增量编译产物清理掉再跑一次完整构建确保成功不是因为复用了之前的产物。第二在 Android Studio 里执行一次 Sync看 IDE 面板是否还是红的——命令行成功但 IDE 报错的情况是存在的通常是因为 IDE 用的是自己那套 Gradle 配置。第三检查生成的 APK 或 jar 里确实包含了 Kotlin 编译产物比如反编译看一下有没有预期的类文件。这三步做完才算真的修好了。如果还是不行把~/.gradle/daemon/下最新的日志文件打开搜索Could not find关键字看看完整堆栈。IDE 面板上显示的往往是被截断过的摘要日志里才有完整信息。我遇到过好几次IDE 上显示的是插件找不到日志里实际上写的是另一个传递依赖解析失败导致插件加载中断方向完全不一样。4. 版本对齐Kotlin、Gradle、AGP 三者怎么配4.1 一张参考对照表版本不匹配是这个报错的高发原因之一尤其是从别处拷来的项目三个版本往往是错位的。下面这张表是基于常见发行版整理的参考区间具体请以官方兼容性文档为准Kotlin 插件版本建议 Gradle 区间说明1.8.x6.8.3 - 7.6早期项目常见组合新 Gradle 上可能提示弃用1.9.x6.8.3 - 8.1.11.9.20 之后对 Gradle 8.x 支持更好2.0.x6.8.3 - 8.5引入 K2 编译器配置项有调整2.1.x7.6.3 - 8.10对旧 Gradle 的支持收窄除了 Kotlin 和 GradleAndroid 项目里还有 Android Gradle Plugin它同样对 Gradle 有硬性要求。三者对齐的实操顺序是先确定 AGP 版本据此确定 Gradle 版本再选择落在兼容区间里的 Kotlin 插件版本。反过来选容易走到死胡同。同时JDK 版本也会参与进来——Gradle 8.x 通常需要 JDK 17 及以上如果你机器上装的是 JDK 8即使版本表上看起来匹配运行时也可能报别的错。这些都是同一条链上的环节不能只看其中一个。4.2 settings.gradle 与 build.gradle 的分工搞清楚文件分工能避免很多改了没反应的困惑。settings.gradle是 Gradle 构建的入口文件它在配置阶段最开始被解析负责定义项目结构、声明插件仓库和依赖仓库。build.gradle是具体项目的构建脚本在 settings 之后执行。所以仓库声明放错文件等于在错误的时间点做正确的事效果为零。一个典型的错误是把镜像地址加到了根build.gradle的allprojects里但插件用的是plugins {}块声明。插件解析发生在pluginManagement阶段早于allprojects生效所以镜像形同虚设。正确做法是把插件相关的仓库放进settings.gradle的pluginManagement里。顺便说下 Kotlin DSL 和 Groovy DSL 的区别因为现在很多新项目默认用build.gradle.kts。两者在功能上等价但在仓库配置的写法上略有差异// settings.gradle.kts pluginManagement { repositories { maven(https://maven.aliyun.com/repository/gradle-plugin) gradlePluginPortal() google() mavenCentral() } }Kotlin DSL 里用maven(url)这种函数调用形式语法错误会在编译期直接暴露比 Groovy 的运行时错误好定位一些。但 Kotlin DSL 的首次配置阶段编译会慢一点这是它的固有代价。选择哪种主要看团队习惯不用纠结。5. 常见问题速查与踩坑记录5.1 问题对照速查表现象可能原因处理方式版本号显示为*版本变量为空或 key 不存在检查版本目录文件和变量名拼写报错带Searched in...且全是境外地址镜像未生效或配错作用域检查pluginManagement里的仓库声明报错夹杂SocketTimeoutException下载中断留下脏缓存加--refresh-dependencies或删对应缓存目录命令行成功IDE 仍报错IDE 使用了独立的 Gradle 配置检查 IDE 设置里的 Gradle 路径与离线开关报错指向传递依赖而非插件本身依赖链上某个包解析失败看完整日志定位真正的失败节点换机器后才出现环境变量或缓存路径不同检查GRADLE_USER_HOME与本地仓库配置这张表可以贴在项目文档里新人接手时能省下大量沟通成本。我现在的习惯是在团队仓库里放一份BUILD_TROUBLESHOOTING.md把这类高频问题的处理步骤写清楚遇到问题时先自查实在解决不了再找人。5.2 几个只有踩过才知道的细节第一个坑是关于缓存目录的。很多人删缓存时只删了caches目录忘了~/.gradle/wrapper/dists和项目根目录下的.gradle文件夹。后两个地方也可能残留损坏的状态。完整的清理应该是停掉 Gradle 守护进程、删除项目下的.gradle目录、必要时清理caches/modules-2然后再重新构建。顺序别搞反先停进程再删文件否则文件会被占用删不掉。第二个坑是 Gradle 守护进程。Gradle 会常驻一个后台进程复用环境改了配置之后如果守护进程还活着有时候新配置不会立刻生效。执行./gradlew --stop可以显式停掉所有守护进程再跑构建就是全新环境。这个操作没有任何副作用遇到诡异问题时值得先试一下。第三个坑是关于版本升级的连锁反应。把 Kotlin 插件从 1.8 升到 2.0 之后编译器行为有变化一些旧代码可能编译不过报错文本和找不到插件完全不同但有些人会误以为是插件没装上。这时候要先确认插件确实加载成功了——看构建日志里有没有 Kotlin 编译任务的输出有就说明插件没问题该去改代码了。第四个坑比较隐蔽某些企业网络会对 HTTPS 请求做中间处理导致证书校验失败。表现是连接超时或者 SSL 握手错误日志里能看到PKIX path building failed之类的字样。这种情况需要把企业根证书导入到 JDK 的信任库里或者改用内网仓库。这不是配置能解决的问题需要和环境管理方沟通。5.3 我的个人配置模板最后把我现在常用的一份最小可用配置放出来新项目直接抄就行。// settings.gradle pluginManagement { repositories { maven { url https://maven.aliyun.com/repository/gradle-plugin } maven { url https://maven.aliyun.com/repository/public } gradlePluginPortal() google() mavenCentral() } } dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS) repositories { maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/google } google() mavenCentral() } } rootProject.name demo include :app// gradle.properties org.gradle.jvmargs-Xmx2048m -Dfile.encodingUTF-8 org.gradle.paralleltrue org.gradle.cachingtrue kotlin.code.styleofficialorg.gradle.parallel开启并行构建org.gradle.caching开启构建缓存这两项对多模块项目提速明显。jvmargs里的堆内存按机器配置调整2G 是个比较安全的起点模块多的话可以加到 4G。这些参数本身不解决找不到插件的问题但能让排查过程少受些性能干扰——构建越慢试错成本越高。真要说经验我最想分享的一点是遇到这类报错先别动手改先花两分钟把日志里Searched in the following locations那几行读完。它会直接告诉你 Gradle 去过哪些地方、有没有去过你期望的地方。九成的找不到问题答案就写在那几行里只是大多数人习惯性地把它们折叠掉了。 Kotlin Gradle插件找不到？完整排查与修复指南
刚接手一个新项目拉下代码打开 Android StudioGradle Sync 转了没两圈就甩出一行红字Could not find org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.24。这种报错在 Kotlin 项目里出现的频率极高尤其是在换电脑、换版本、换网络环境之后几乎每个写过 Kotlin 的同学都至少撞上过一两次。它看起来吓人但本质上是一个非常明确的地址找不到问题——Gradle 拿着你给的坐标去仓库里敲门敲了一圈没人应。真正麻烦的地方在于导致没人应的原因有好几种配置写错、仓库没配、版本号对不上、本地缓存脏了、离线模式开着都会呈现出几乎一模一样的错误文本所以很多人第一反应是去删缓存、重启 IDE来回折腾半小时也没解决。这篇文章就是围绕这个报错展开的完整排查与修复手册。我会先说清楚kotlin-gradle-plugin到底是什么、它在构建流程里扮演什么角色再把可能的原因拆成四类逐一分析然后给出一套从确认坐标到验证结果的可复现流程包含镜像仓库配置、离线场景兜底、版本对齐表以及一堆我自己踩过的坑。不管你是刚开始学 Kotlin 的新手还是已经带过几个 Android 项目的开发者只要你的构建脚本里出现了 Kotlin 插件这篇内容都能直接拿去对照使用。1. 先把报错信息本身拆开看1.1 一行错误里其实藏着三个关键信息Could not find org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.24这行字按 Maven 坐标的格式可以切成三段groupId是org.jetbrains.kotlinartifactId是kotlin-gradle-plugin最后那个冒号后面的1.9.24是版本号。这三段合起来就是 Gradle 要去仓库里找的唯一地址。而错误里如果版本号位置显示的是星号比如kotlin-gradle-plugin:*那说明问题出在版本压根没被解析出来而不是版本号写错了——这两种情况的排查方向完全不同。前者意味着 Gradle 明确知道要哪个版本但去的仓库里没有这个版本的文件后者意味着你的构建脚本在依赖声明阶段就没有把版本传进去Gradle 只能拿着一个通配符去问仓库你有没有这个包的任意版本仓库答复我不知道你要哪个版本于是报错。实际项目里星号出现得还挺多常见于版本变量拼写错误、ext属性没定义、libs.versions.toml里的 key 对不上、或者根项目和子项目的插件声明方式混用。另外要注意错误信息前面往往还有一行上下文比如 Could not resolve all files for configuration :app:classpath或者Could not resolve org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.24甚至后面跟着一串Searched in the following locations。那段Searched in the following locations才是真正值钱的东西它会把 Gradle 实际去过的每一个仓库地址列出来。多数人只盯着第一行红字看忽略了下面那一长串结果就是盲目试错。我的习惯是先把这串地址完整看一遍确认里面有没有我期望的仓库如果没有问题基本一眼就能定位。1.2 kotlin-gradle-plugin 在构建流程里的位置很多人对这个包的印象停留在Kotlin 项目要加的一个依赖其实它的角色比这重要得多。Kotlin 代码最终要编译成 JVM 字节码而 Gradle 本身并不认识 Kotlin它只认识一套通用的构建任务模型。kotlin-gradle-plugin就是那个中间人它向 Gradle 注册compileKotlin、kotlinOptions、KotlinCompile任务类型这些扩展点把 Kotlin 编译器的行为包装成 Gradle 能理解的任务。没有它你的.kt文件在 Gradle 眼里就是一堆无意义的文本。这也解释了为什么它必须出现在构建脚本的 classpath 上而不是普通依赖里。用 Groovy DSL 的传统写法是这样的buildscript { repositories { google() mavenCentral() } dependencies { classpath org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.24 } }这段代码的意思是在配置阶段开始之前先把 Kotlin 插件的 jar 包下载下来加载到构建脚本的类加载器里。注意buildscript块里有自己的repositories它和你allprojects里配的仓库是两套东西。这个细节是大量报错的源头——很多人在allprojects里老老实实配了镜像却没意识到buildscript块走的还是默认仓库插件照样下不下来。新版本的 Gradle 更推荐用plugins块加settings.gradle里的pluginManagement// settings.gradle pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } }两种写法定位仓库的路径不一样排查的时候必须分清当前项目用的是哪一套。我在接手别人代码时第一步永远是先看settings.gradle有没有pluginManagement块再看根build.gradle有没有buildscript块两者都有的话说明项目处在迁移中间态最容易出问题。1.3 为什么这个包特别容易找不到对比一下其他依赖会发现kotlin-gradle-plugin的报错率明显偏高原因有这么几个。一是它的发布渠道比较特殊同时存在于 Maven Central 和 Gradle Plugin Portal两个仓库的索引结构不同用plugins {}块解析时要走 plugin marker 机制也就是会先去查org.jetbrains.kotlin.jvm:org.jetbrains.kotlin.jvm.gradle.plugin这个标记包再由它指向真正的实现包中间任何一环断了都会报找不到。二是它和 Kotlin 编译器版本强绑定。你写1.9.24就必须真的有1.9.24这个发行版而且这个版本还必须支持你当前的 Gradle 版本。Kotlin 官方对 Gradle 的支持区间是有限制的太新的 Gradle 配太旧的 Kotlin 插件或者反过来都可能出现解析异常。三是国内网络环境的现实情况。Maven Central 和 Gradle Plugin Portal 的服务器都在境外直连下载大文件时超时、中断的比例不低。一次没下完Gradle 会在缓存目录里留下不完整的记录下次同步时它以为已有缓存直接跳过下载结果加载时失败——表现出的错误文本和仓库里没有几乎一样。这个坑我在早些年遇到过好几次最后发现根本不是配置问题而是缓存里躺着一个 0 字节的 jar。2. 四类根因按概率从高到低排查2.1 仓库声明缺失或写错了作用域这是最常见的一类。典型场景是我配了mavenCentral()但项目用的是plugins {}块而pluginManagement里的仓库列表被我改成了只有公司内网仓库。又或者项目里只有google()和mavenCentral()但某个依赖被发布到了gradlePluginPortal自然就找不到。还有一种更隐蔽的情况仓库配了但配在了错误的位置。Gradle 的仓库作用域有好几层——pluginManagement管插件解析buildscript管构建脚本依赖dependencyResolutionManagement管项目依赖allprojects是给所有子项目加仓库。这四层互不覆盖你在allprojects里加的镜像对buildscript完全无效。我见过一个项目开发同学把阿里云镜像仔仔细细加到了allprojects.repositories里然后抱怨插件还是下不下来就是因为插件走的是buildscript那条路。判断方法很简单看错误信息里Searched in the following locations后面的地址列表。如果列表里全是境外的默认地址说明你的镜像根本没生效如果列表是空的或者只有一两个奇怪的地址说明仓库声明本身就没被执行到。以我的经验这一条能覆盖六成以上的同类报错。2.2 版本号写错或者三方版本互相不兼容版本问题的表现形式有两种。一种是纯粹的手滑比如把1.9.24写成1.9.2、1.9.4这种不存在的版本号或者把kotlin_version变量名拼错导致值变成了空字符串。这种情况下 Gradle 会老老实实去查一个不存在的版本报错文本中版本号是完整的数字看起来很正常但实际上仓库里没有这个发行版。另一种是版本互相打架。Kotlin 插件对 Gradle 版本有明确的兼容区间Android Gradle Plugin 又对 Gradle 版本有自己的要求三者关系可以简化成AGP 决定 Gradle 能用哪个大版本Kotlin 插件决定它能不能在某个 Gradle 版本上跑起来。举个例子如果你的项目用了较新的 Android Gradle Plugin它可能强制要求 Gradle 8.x而项目里声明的 Kotlin 插件版本还停留在比较早的发行版这个组合在某些边角情况下就会出现解析或加载异常。正确做法是把三个版本拉到一个经过验证的组合上不要随便单独升级其中一个。这里我要特别提醒一句不要迷信最新版本一定最好。我在项目里见过把 Kotlin 插件直接拉到最新主版本结果因为语法变更和已有代码不兼容编译期报出一堆莫名其妙的错误最后还得回退。稳定优先是构建配置里最朴素也最有效的原则。2.3 网络中断导致的半吊子缓存这类问题最气人因为它伪装得特别好。Gradle 下载依赖时如果连接中断会在~/.gradle/caches/modules-2/files-2.1/下面创建目录结构但内容不完整。下次构建时 Gradle 检查缓存发现目录存在就认为这个依赖我已经有了直接跳过网络请求。等到真正加载时发现文件读不出来于是抛出解析失败。判断这类问题有一个很直接的信号报错信息里偶尔会夹杂java.net.SocketTimeoutException、Connection reset或者Read timed out这类底层异常。如果你看到这些字样基本可以确定是网络链路的问题而不是配置写错。这时候光改仓库地址没用必须先把脏缓存清掉。缓存目录的位置按平台不同会有差异Linux 和 macOS 下是~/.gradle/caches/Windows 下是C:\Users\你的用户名\.gradle\caches\。要清理某个具体依赖可以直接删对应的 group 目录比如caches/modules-2/files-2.1/org.jetbrains.kotlin/。但更稳妥的做法是保留缓存目录、只加--refresh-dependencies参数跑一次让 Gradle 重新校验。我在实际项目里倾向于后者因为全量删缓存意味着所有依赖重新下载网络不好的时候要等很久。2.4 离线模式与本地环境配置互相干扰Gradle 有一个--offline开关开启后所有依赖都从本地缓存取不再访问网络。这个开关本意是给网络受限环境用的但如果残留配置没清掉就会出现明明有网却怎么都下不下来的情况。Android Studio 的 Gradle 设置面板里有个 Offline work 复选框命令行里也可以加--offline两处都可能被之前的人打开过。另外还有两个容易被忽略的环境项。一个是GRADLE_USER_HOME环境变量如果它被指向了一个空的或者不完整的目录Gradle 会去那里找缓存自然找不到报错和仓库没有一模一样。另一个是gradle.properties里可能存在的代理相关配置如果之前配置过某些网络转发参数而目标服务已经不可用Gradle 会尝试走那条路然后超时。排查时先把这两个地方确认一遍能省下不少时间。3. 一套可以照着做的修复流程3.1 第一步确认你要的坐标和版本到底是什么动手改配置之前先把信息确认清楚这比直接乱试有效得多。打开根目录的build.gradle搜索kotlin看插件是怎么声明的再打开settings.gradle看有没有pluginManagement块如果项目用了版本目录Version Catalog还要去看gradle/libs.versions.toml。[versions] kotlin 1.9.24 [plugins] kotlin-jvm { id org.jetbrains.kotlin.jvm, version.ref kotlin }Version Catalog 的好处是版本集中管理坏处是 key 写错时报错信息会比较绕。我遇到过version.ref指到一个不存在的版本 key结果解析出来的版本号是空报错里就带着星号。所以看到星号第一个要查的就是版本目录文件里的 key 名是否对得上。确认完版本之后去 Maven Central 的官网搜一下这个坐标看对应版本是否真实存在、发布时间是什么时候。这一步花不了两分钟但能排除掉一大半版本号打错了的情况。顺便也能确认这个版本有没有被撤回过——极少数情况下发行版会因为严重问题被下架。3.2 第二步把仓库声明补齐并且补在正确的位置确认坐标没问题之后开始配仓库。如果你的项目能访问外网但速度慢用镜像是最省事的方案。下面是一份我常用的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 { repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS) repositories { maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/google } google() mavenCentral() } }有几个细节必须说清楚。第一镜像地址要放在前面官方地址放在后面兜底。Gradle 是按声明顺序依次查询的镜像靠前意味着优先走镜像镜像没有的包再回落到官方源这样既不丢包又能提速。第二repositoriesMode这个设置很关键PREFER_SETTINGS表示优先用 settings 里声明的仓库FAIL_ON_PROJECT_REPOS更严格会直接禁止子项目自己声明仓库——如果你的项目还在根build.gradle里写allprojects { repositories { ... } }用FAIL_ON_PROJECT_REPOS会直接报错需要同步把那段删掉或改成PREFER_SETTINGS。第三buildscript方式的老项目要在build.gradle里单独配一份buildscript { repositories { maven { url https://maven.aliyun.com/repository/gradle-plugin } maven { url https://maven.aliyun.com/repository/public } google() mavenCentral() } dependencies { classpath org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.24 } }两套配置都写上并不冲突属于稳妥的冗余。等确认构建能跑通之后再考虑精简。注意镜像仓库的地址和路径会随时间调整配置前建议先确认当前可用的地址不要直接复制几年前的旧链接。3.3 第三步清理脏缓存强制重新解析仓库配好之后先别急着相信它生效了。执行下面这条命令让 Gradle 忽略本地缓存、重新走一遍解析./gradlew --refresh-dependencies clean assembleDebugWindows 下把./gradlew换成gradlew.bat即可。--refresh-dependencies的作用是让 Gradle 重新校验所有依赖的元数据包括那些它认为已经在缓存里的包。如果这一步能顺利通过说明问题确实出在缓存或者仓库配置上如果还是报同样的错就要回头看第二步的配置是不是真的生效了。判断配置是否生效有个小技巧在命令后面加上--info或--debug日志里会打印出实际使用的仓库列表。搜索Repository相关的行看看你配的镜像地址在不在里面。如果不方便看日志也可以临时把网络断开再跑一次——如果此时错误信息里出现了更多境外地址的超时提示说明镜像没被用上。3.4 第四步完全离线的环境怎么办有些场景是真的没有外网比如内网构建机、隔离环境。这种情况下有几条路可以走。第一条路是把依赖预先下载好放到本地 Maven 仓库目录里然后在构建脚本里加上mavenLocal()。Gradle 会去~/.m2/repository找包路径结构必须完全符合 Maven 规范org/jetbrains/kotlin/kotlin-gradle-plugin/1.9.24/下面要有 jar 和 pom 文件。这个方法的好处是干净坏处是依赖传递需要自己补齐缺一个就报一次错比较费功夫。第二条路是用公司或团队自建的私有仓库把外部依赖提前同步进去构建时统一指向内网地址。这也是团队协作里最推荐的做法一次配置全员受益还能避免每个人环境不一致带来的差异。第三条路是把整台机器的 Gradle 缓存目录打包复制到目标机器上。这个办法最简单粗暴但要注意缓存目录里的路径包含用户名和哈希值跨平台复制的成功率不稳定Linux 之间相对可靠跨系统基本别指望。如果只是临时断网加--offline参数跑一次也行./gradlew --offline assembleDebug前提是缓存里确实有完整的包。这个方法适合在飞机上或者地铁里改代码的场景但不要长期开着离线模式否则新增依赖时会一直失败。3.5 第五步确认问题真的解决了看到BUILD SUCCESSFUL只是第一步。我的习惯是再做三件事来确认。第一把构建缓存和增量编译产物清理掉再跑一次完整构建确保成功不是因为复用了之前的产物。第二在 Android Studio 里执行一次 Sync看 IDE 面板是否还是红的——命令行成功但 IDE 报错的情况是存在的通常是因为 IDE 用的是自己那套 Gradle 配置。第三检查生成的 APK 或 jar 里确实包含了 Kotlin 编译产物比如反编译看一下有没有预期的类文件。这三步做完才算真的修好了。如果还是不行把~/.gradle/daemon/下最新的日志文件打开搜索Could not find关键字看看完整堆栈。IDE 面板上显示的往往是被截断过的摘要日志里才有完整信息。我遇到过好几次IDE 上显示的是插件找不到日志里实际上写的是另一个传递依赖解析失败导致插件加载中断方向完全不一样。4. 版本对齐Kotlin、Gradle、AGP 三者怎么配4.1 一张参考对照表版本不匹配是这个报错的高发原因之一尤其是从别处拷来的项目三个版本往往是错位的。下面这张表是基于常见发行版整理的参考区间具体请以官方兼容性文档为准Kotlin 插件版本建议 Gradle 区间说明1.8.x6.8.3 - 7.6早期项目常见组合新 Gradle 上可能提示弃用1.9.x6.8.3 - 8.1.11.9.20 之后对 Gradle 8.x 支持更好2.0.x6.8.3 - 8.5引入 K2 编译器配置项有调整2.1.x7.6.3 - 8.10对旧 Gradle 的支持收窄除了 Kotlin 和 GradleAndroid 项目里还有 Android Gradle Plugin它同样对 Gradle 有硬性要求。三者对齐的实操顺序是先确定 AGP 版本据此确定 Gradle 版本再选择落在兼容区间里的 Kotlin 插件版本。反过来选容易走到死胡同。同时JDK 版本也会参与进来——Gradle 8.x 通常需要 JDK 17 及以上如果你机器上装的是 JDK 8即使版本表上看起来匹配运行时也可能报别的错。这些都是同一条链上的环节不能只看其中一个。4.2 settings.gradle 与 build.gradle 的分工搞清楚文件分工能避免很多改了没反应的困惑。settings.gradle是 Gradle 构建的入口文件它在配置阶段最开始被解析负责定义项目结构、声明插件仓库和依赖仓库。build.gradle是具体项目的构建脚本在 settings 之后执行。所以仓库声明放错文件等于在错误的时间点做正确的事效果为零。一个典型的错误是把镜像地址加到了根build.gradle的allprojects里但插件用的是plugins {}块声明。插件解析发生在pluginManagement阶段早于allprojects生效所以镜像形同虚设。正确做法是把插件相关的仓库放进settings.gradle的pluginManagement里。顺便说下 Kotlin DSL 和 Groovy DSL 的区别因为现在很多新项目默认用build.gradle.kts。两者在功能上等价但在仓库配置的写法上略有差异// settings.gradle.kts pluginManagement { repositories { maven(https://maven.aliyun.com/repository/gradle-plugin) gradlePluginPortal() google() mavenCentral() } }Kotlin DSL 里用maven(url)这种函数调用形式语法错误会在编译期直接暴露比 Groovy 的运行时错误好定位一些。但 Kotlin DSL 的首次配置阶段编译会慢一点这是它的固有代价。选择哪种主要看团队习惯不用纠结。5. 常见问题速查与踩坑记录5.1 问题对照速查表现象可能原因处理方式版本号显示为*版本变量为空或 key 不存在检查版本目录文件和变量名拼写报错带Searched in...且全是境外地址镜像未生效或配错作用域检查pluginManagement里的仓库声明报错夹杂SocketTimeoutException下载中断留下脏缓存加--refresh-dependencies或删对应缓存目录命令行成功IDE 仍报错IDE 使用了独立的 Gradle 配置检查 IDE 设置里的 Gradle 路径与离线开关报错指向传递依赖而非插件本身依赖链上某个包解析失败看完整日志定位真正的失败节点换机器后才出现环境变量或缓存路径不同检查GRADLE_USER_HOME与本地仓库配置这张表可以贴在项目文档里新人接手时能省下大量沟通成本。我现在的习惯是在团队仓库里放一份BUILD_TROUBLESHOOTING.md把这类高频问题的处理步骤写清楚遇到问题时先自查实在解决不了再找人。5.2 几个只有踩过才知道的细节第一个坑是关于缓存目录的。很多人删缓存时只删了caches目录忘了~/.gradle/wrapper/dists和项目根目录下的.gradle文件夹。后两个地方也可能残留损坏的状态。完整的清理应该是停掉 Gradle 守护进程、删除项目下的.gradle目录、必要时清理caches/modules-2然后再重新构建。顺序别搞反先停进程再删文件否则文件会被占用删不掉。第二个坑是 Gradle 守护进程。Gradle 会常驻一个后台进程复用环境改了配置之后如果守护进程还活着有时候新配置不会立刻生效。执行./gradlew --stop可以显式停掉所有守护进程再跑构建就是全新环境。这个操作没有任何副作用遇到诡异问题时值得先试一下。第三个坑是关于版本升级的连锁反应。把 Kotlin 插件从 1.8 升到 2.0 之后编译器行为有变化一些旧代码可能编译不过报错文本和找不到插件完全不同但有些人会误以为是插件没装上。这时候要先确认插件确实加载成功了——看构建日志里有没有 Kotlin 编译任务的输出有就说明插件没问题该去改代码了。第四个坑比较隐蔽某些企业网络会对 HTTPS 请求做中间处理导致证书校验失败。表现是连接超时或者 SSL 握手错误日志里能看到PKIX path building failed之类的字样。这种情况需要把企业根证书导入到 JDK 的信任库里或者改用内网仓库。这不是配置能解决的问题需要和环境管理方沟通。5.3 我的个人配置模板最后把我现在常用的一份最小可用配置放出来新项目直接抄就行。// settings.gradle pluginManagement { repositories { maven { url https://maven.aliyun.com/repository/gradle-plugin } maven { url https://maven.aliyun.com/repository/public } gradlePluginPortal() google() mavenCentral() } } dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS) repositories { maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/google } google() mavenCentral() } } rootProject.name demo include :app// gradle.properties org.gradle.jvmargs-Xmx2048m -Dfile.encodingUTF-8 org.gradle.paralleltrue org.gradle.cachingtrue kotlin.code.styleofficialorg.gradle.parallel开启并行构建org.gradle.caching开启构建缓存这两项对多模块项目提速明显。jvmargs里的堆内存按机器配置调整2G 是个比较安全的起点模块多的话可以加到 4G。这些参数本身不解决找不到插件的问题但能让排查过程少受些性能干扰——构建越慢试错成本越高。真要说经验我最想分享的一点是遇到这类报错先别动手改先花两分钟把日志里Searched in the following locations那几行读完。它会直接告诉你 Gradle 去过哪些地方、有没有去过你期望的地方。九成的找不到问题答案就写在那几行里只是大多数人习惯性地把它们折叠掉了。