最近在搭一个新项目Android Studio 一点 SyncGradle 跑了不到两分钟就开始飘红Could not resolve org.jetbrains.kotlin:kotlin-stdlib:1.9.24。这种报错对 Android 开发者来说太熟悉了——Kotlin 依赖下载失败几乎每个用 Kotlin 写项目的团队都会碰到而且每次触发的原因可能都不一样。更气人的是有时候同样的配置同事那边一次过你这边就是下不下来玄学得很。这篇就把我啃过的骨头、试过的方案、总结出来的排查顺序一次性整理出来。先说清楚这不是什么高深技术就是一套实战排查手册适合刚入坑 Android 的新人也适合被 Gradle 同步折磨到怀疑人生的中级开发者甚至有人在 CI 上偶发构建失败也能从这里找到对应的解法。1. 先搞清楚Kotlin 依赖下载失败到底是什么原因1.1 别急着改配置先看报错长什么样很多人一看到依赖下载失败就条件反射去找镜像源结果改了半天还是不行。我的经验是先把报错完整读一遍不同报错指向的根因完全不一样。最常见的几类报错信息Could not resolve org.jetbrains.kotlin:kotlin-stdlib:1.9.24——这是最笼统的说法意思是 Gradle 在声明的仓库里都没找到这个依赖或者仓库源压根连不上。Could not GET https://...——这种说明 Gradle 确实尝试去某个仓库地址拉文件了但请求失败了可能是超时、连接被重置也可能是这个地址返回了错误状态码。SSLHandshakeException——证书相关的问题多半是你用了某个仓库地址但本地 Java 环境的证书链不认它。这种情况在 Android Studio 内置 JDK 版本比较老的时候特别常见。Checksum mismatch或unexpected end of archive——这不是网络问题是 Gradle 本地缓存里已经躺了一个损坏的文件下载中断、磁盘写入异常都可能造成后面专门讲缓存处理。Could not find kotlin-stdlib后面跟着一串“Searched in the following locations”——这是最有用的一种报错Gradle 会把它搜索过哪些仓库地址、找到了什么文件、缺哪个文件全都列出来。我的习惯是遇到报错先截屏或者复制完整日志不用急着查从日志里找三样东西下载失败的依赖坐标group:artifact:version、报错发生在哪个仓库、有没有缓存相关关键词。这三样定位完问题基本就缩小到一小片区域了。1.2 六个根因逐个拆开讲根据我这几年踩坑的经验Kotlin 依赖下载失败的原因可以归纳成六大类按出现频率排序第一仓库地址不可达或网络波动。这是最普遍的尤其 mavenCentral() 和 google() 这两个默认仓库服务器都在海外访问质量时好时坏。Gradle 拉依赖是串行的一个仓库连接超时要等很久才轮到下一个表现出来就是整个同步卡住然后报错。第二仓库声明顺序不对。Gradle 按照配置顺序从上往下查找依赖找到第一个包含该依赖的仓库就会停住。如果你先声明了一个速度极慢甚至不可达的仓库那每次同步都会先卡在那个仓库上。第三依赖坐标写错或者版本号不存在。常见的有把kotlin-stdlib的 group 写错、artifact 名大小写搞混、版本号打了个不存在的 tag。这种情况不管你换多少个镜像源都没用因为任何仓库里都没有这个东西。第四版本冲突与传递依赖问题。Kotlin Gradle Plugin 和 Android Gradle Plugin 之间、Kotlin 版本和协程版本之间都存在兼容矩阵有时候不是下载失败而是下载下来的版本之间互相打架导致构建中断表现却像依赖解析失败。第五本地缓存损坏。前面提到过Gradle 下载一半断网、磁盘空间不够、杀毒软件拦了文件都可能导致缓存里躺着一个坏文件。Gradle 优先使用缓存坏文件不清理问题就一直存在。第六构建环境与 Gradle 版本不匹配。Android Studio 内置的 JBRJetBrains Runtime版本、Gradle 发行版版本、AGP 版本这三个只要有一个明显偏老解析 Kotlin DSL 脚本时可能抛出奇怪异常让人误以为是依赖下载问题。这六个原因里我自己碰到最多的是一、二、五这三个加起来占了八成以上的场景。接下来的内容我会按“先网络后配置、先缓存后脚本”的顺序把每一步怎么操作、怎么验证讲透。2. 仓库配置最值得优化的一个环节2.1 为什么默认仓库会卡住新建 Android 项目的时候settings.gradle里默认写的是google()和mavenCentral()。这套配置官方推荐但实际体验就是不稳定。google()仓库的主要作用是从 Google 的 Maven 仓库拉取 AndroidX、AGP 这些构件mavenCentral()是 Sonatype 维护的 Maven 中央仓库Kotlin 标准库、协程库很多都在这里。关键在于这两个仓库的服务器都不在国内。Gradle 解析依赖的时候是同步串行请求每个仓库连接超时的时间默认是 30 秒如果某个仓库响应慢一次同步就可能拖出十几分钟。用生活类比就是你明明下楼走两步就能在便利店买到酱油非要去等一个海外代购等了一周还没到结果锅里的菜全糊了。所以想从根本上缓解下载问题第一步就是调整仓库配置把国内能稳定访问的公共镜像仓库放到最前面。注意我说的是“缓解”不是“根治”——镜像仓库再快也架不住依赖坐标写错这种主观问题。2.2 国内镜像仓库怎么选public 镜像里最常用的是阿里云的公共仓库地址是https://maven.aliyun.com/repository/public。这个仓库同步了 Maven Central 和 JCenter 的内容绝大部分开源库都能找到。Google 相关的构件比如 AndroidX、AGP、Compose需要单独用https://maven.aliyun.com/repository/google。Gradle 插件本身也有一个代理地址https://maven.aliyun.com/repository/gradle-plugin。我实测下来的组合是google public gradle-plugin三个地址覆盖日常项目的绝大部分依赖。腾讯云也有类似的镜像但阿里云这几个地址在文档、社区例子、团队协作里更通用所以优先推荐前者。还有一个容易踩的细节public里其实已经聚合了 central 和 jcenter但它不包含 google 的构件所以不要只配一个public就完事google那个一定要单独加。另外如果你的项目用了自建私服比如企业内部搭建的 Sonatype Nexus 或者 JFrog Artifactory那就在镜像源之前加上私服地址并且做好权限配置。这里不展开讲私服运维只说一点私服地址不要写在镜像仓库后面否则每次拉取外部依赖都会先去私服搜一遍如果私服本身没有做代理转发就会白白增加一次超时等待。2.3 一份可以直接抄的 settings.gradle 配置新版 Android Studio 项目统一用settings.gradle配置仓库推荐把镜像写在pluginManagement和dependencyResolutionManagement两个块里。前者管 Gradle 插件本身的下载后者管项目依赖。直接给你一份我目前最常用的配置pluginManagement { repositories { maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/gradle-plugin } maven { url https://maven.aliyun.com/repository/public } mavenCentral() google() } } dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/public } mavenCentral() google() } }注意几个关键点镜像仓库放在最前面官方仓库放在最后兜底。这样在镜像仓库能找到的依赖Gradle 根本不会去访问慢速源万一镜像仓库没有某个极其冷门的依赖兜底源还能补上。FAIL_ON_PROJECT_REPOS这个模式的含义是禁止在模块级build.gradle里再去声仓储库。以前老项目喜欢在根项目的allprojects块里写仓库配置新版本 Gradle 里这种做法会被判定为不推荐。强制统一在settings.gradle里管理好处是仓库配置只维护一份团队协作时不会出现“我本地换了镜像源你那边还是老的”这种分叉。如果项目里还有老代码在根目录build.gradle里写了类似这样的内容allprojects { repositories { maven { url https://maven.aliyun.com/repository/public } } }建议逐步迁移到settings.gradle留着也不是不能跑但可能触发RepositoriesMode.FAIL_ON_PROJECT_REPOS的报错到时候更麻烦。配置改完以后记得点一下 Android Studio 里的 “Sync Now”等它跑完看结果。如果还是报错别急接着往下看缓存和版本兼容问题。3. 本地缓存从“删了试试”到“有章可循”3.1 Gradle 缓存放哪了Gradle 把下载过的依赖缓存在本机的.gradle目录里路径按操作系统区分WindowsC:\Users\你的用户名\.gradle\caches\modules-2\files-2.1macOS / Linux~/.gradle/caches/modules-2/files-2.1在这个目录下依赖按照group/artifact/version三层目录组织。比如org.jetbrains.kotlin:kotlin-stdlib:1.9.24对应的路径就是org.jetbrains.kotlin/kotlin-stdlib/1.9.24/。这个目录里每个依赖会存下.pom、.aar、.jar、.module等文件以及一个.sha1校验文件。Gradle 再次解析到同一个依赖时优先从缓存读取只有缓存里没有或者校验失败时才会重新去远程仓库拉取。理解这个机制非常重要因为很多下载失败的“玄学”本质上是缓存里躺着一个坏文件。举一个真实案例我之前遇到一个项目androidx.core:core-ktx一直解析失败换镜像、清 Gradle 进程都试了没用。最后手动打开缓存目录发现那个版本目录下有一个.aar文件是 0 字节旁边的.part后缀文件还没合并完。这就是某次下载被中断残留的产物Gradle 校验不过反复去远程拿又反复失败。3.2 缓存损坏怎么判断判断缓存是否损坏有几个办法。看报错关键词如果报错信息里有Checksum mismatch、unexpected end of archive、No cached version available for offline mode、file not found基本都是缓存有问题。看缓存文件大小到缓存目录找到对应依赖的目录看.aar或.jar文件的大小如果明显小得离谱比如几十字节八成是坏文件。正常情况一个core-ktx的 aar 少说也有几十 KB。看有没有残留临时文件目录里出现.part、.lock后缀的文件说明之前有下载任务没正常结束。还有一种更隐蔽的情况缓存里文件本身大小正常但内容被锁或者权限不对导致 Gradle 读取失败。这个在 Windows 上偶发多半是杀毒软件实时扫描锁住了文件。3.3 安全的清理思路很多人一遇到依赖问题就删整个.gradle目录这不是不行但代价太大。删掉整个目录意味着所有项目缓存的依赖都要重新下载几百 MB 甚至几个 GB 的流量白花了而且下载过程本身就容易再次触发网络问题。我的推荐做法是精准删除关闭 Android Studio确保没有 Gradle 进程占用文件。根据报错信息找到失败的依赖坐标比如org.jetbrains.kotlin:kotlin-stdlib:1.9.24。进入缓存目录定位到org.jetbrains.kotlin/kotlin-stdlib/1.9.24/把整个版本目录删掉。重新打开项目执行 Sync。如果报错涉及多个依赖或者你懒得一个个找可以直接删除modules-2目录。这个目录只缓存依赖不影响 Gradle 本身和已有的 Wrapper 发行版删掉后所有依赖会重新下载但至少不会让你从头配置一遍环境。在 macOS/Linux 上可以直接用命令rm -rf ~/.gradle/caches/modules-2Windows 上就把C:\Users\你的用户名\.gradle\caches\modules-2这个文件夹删掉。删完以后重新同步大概率能解决缓存损坏类问题。3.4 手动装一个依赖进本地仓库的兜底方案有时候某个依赖比较冷门镜像仓库没有官方仓库又实在连不上。这种情况下有一个非常实用的兜底手段手动把依赖文件安装到本地 Maven 仓库。假设你手里有一个aar文件要从本地引入操作方法是把.aar文件放到一个临时目录比如~/Downloads/。执行 Maven 安装命令mvn install:install-file \ -Dfile~/Downloads/demo.aar \ -DgroupIdcom.example \ -DartifactIddemo \ -Dversion1.0.0 \ -Dpackagingaar项目build.gradle的依赖声明保持不变implementation com.example:demo:1.0.0同时确保仓库配置里包含mavenLocal()。mavenLocal()会优先查找本机~/.m2/repositoryWindows 是C:\Users\用户名\.m2\repository下的依赖因为我们手动执行过安装命令本地仓库里已经有了对应坐标的文件Gradle 不需要去远程拿。这个方案对于私有 SDK 集成特别有用。有些第三方 SDK 厂商给的是一个aar文件没有上传到公共 Maven 仓库又赶时间没法搭私服手动装到本地仓库就是最高效的做法。缺点也明显换一台电脑就得重新装一遍团队协作不太方便所以只能当兜底用不能当常规方案。4. 常见问题与排查技巧实录4.1 我实测遇到的 5 个高频问题把这几年帮同事排查、自己在群里答疑碰到的典型问题整理成一张速查表方便直接对照现象直接原因最快解法Kotlin 标准库下载失败但项目里其他依赖正常Kotlin 版本与仓库不同步或镜像仓库缺该版本换成稳定版 Kotlin 版本检查仓库配置顺序KGPKotlin Gradle Plugin插件下载失败插件仓库没配置对确认pluginManagement里有gradle-plugin镜像地址Android Studio 的 External Libraries 里完全没有 Maven 依赖同步没跑成功或者仓库配置在模块级不生效统一在settings.gradle配置仓库执行完整 SyncIDEA 里 Maven 依赖爆红本地仓库缓存损坏或依赖未下载重新导入项目清缓存删modules-2再同步同一个依赖第一次 Sync 成功第二次失败缓存文件损坏或网络偶发超时删除该依赖的缓存目录重新同步尤其要把第四条和第二条单拎出来说。IDEA 里 Maven 依赖爆红十次有八次是本地仓库里有坏文件剩下两次是仓库地址没生效。而 KGP 插件下载失败很多人会忽略pluginManagement这个块只改dependencyResolutionManagement结果插件还是走的海外源自然会卡。4.2 三板斧排查法如果前面那些配置都检查过了问题还没解决那就按下面这套三板斧来基本能定位九成问题。第一板斧看完整日志而不是只看 Build Output 的第一行。Android Studio 底部工具栏切到 “Build” 面板再切到 “Gradle Sync” 或者直接在终端跑./gradlew help拿完整日志。完整日志会告诉你依赖是从哪个仓库找不到的有没有缓存校验错误哪一步超时信息量完全不同。第二板斧从报错中提取下载失败的坐标然后手动在浏览器里打开对应的仓库地址。比如报错说org.jetbrains.kotlin:kotlin-stdlib:1.9.24找不到那我就在浏览器里访问https://maven.aliyun.com/repository/public/org/jetbrains/kotlin/kotlin-stdlib/1.9.24/如果这个地址能正常打开能看到.pom和.aar文件说明镜像仓库里有货问题出在 Gradle 配置或者缓存上。如果地址打不开或者找不到对应版本那就是版本号写错了或者这个仓库压根没同步这个版本。这一步能快速把“网络问题”和“配置问题”分开省去大量瞎折腾。第三板斧切离线模式验证。在 Android Studio 的 Gradle 工具窗口里勾选 “Offline Work”或者执行./gradlew --offline help如果离线模式下项目能正常解析说明所有依赖都已经在本地缓存里问题跟网络无关把注意力放到构建脚本和插件版本上。如果离线模式都失败Gradle 会明确告诉你缺哪个依赖这时候去补充镜像源或手动下载该依赖就行。4.3 排查时的几个细节习惯再分享几个我在实际排查中发现很有用的细节习惯。第一改完仓库配置以后一定要留意 Gradle 窗口里的 “Refresh” 和 “Sync” 按钮。有时候你只改了文件没点 Sync问题还挂在那但看起来像是没效果。不要以为改完文件就完事了一切以 Sync 成功为准。第二注意 Gradle 版本和 Kotlin 插件版本的兼容性。Kotlin 1.9 及以上版本对 Gradle 版本有最低要求比如 Kotlin 1.9.24 要求 Gradle 6.8.3 以上AGP 版本也有对应要求。如果你用的是特别老的 Gradle插件解析阶段就会异常表现出来还是“依赖无法下载”。遇到这种情况去官方兼容性表格核对一下版本矩阵比反复清缓存有效得多。第三项目换了电脑或者换了网络环境时如果依赖突然大面积失败先重新执行一次完整同步而不要马上删除所有缓存。我刚工作时犯过一个错误新电脑第一次同步项目因为网络慢超时了我直接删了.gradle目录结果触发了全量依赖重新下载耗时更久还额外引入了新的网络波动风险。正确的做法是重试同步等待时间拉长让 Gradle 把超时重试做完。如果连续重试三次都失败再考虑清缓存。第四如果你在公司内网开发存在自建镜像或者内网源优先用内网源不用犹豫。内网源的稳定性和速度远高于公网镜像团队统一配置也方便。5. 我的经验总结与最后的建议5.1 从依赖下载失败到稳定构建的完整操作顺序整个过程看起来步骤多但真正执行起来是可以一套组合拳打下来的。我自己现在处理 Kotlin 依赖下载失败的标准顺序是这样的完整复制报错日志提取依赖坐标和关键词。确认仓库配置重点检查settings.gradle里两个仓库块和镜像源顺序。用浏览器手动访问仓库地址确认这个依赖是否真实存在。如果依赖存在但 Gradle 拉不下来删除对应缓存目录重新同步。如果依赖不存在检查版本号是否写错或者需要升级构建工具版本。如果仍然失败切离线模式判断是不是还有未缓存的依赖再针对缺的那个单独处理。这套顺序看起来朴素但每一步都在缩小问题范围不靠运气不靠猜。5.2 把踩坑经验前置到项目初始化阶段最后说一个被反复教育之后养成的习惯不要在项目出问题的时候才开始想仓库配置而是在新建项目的第一次同步前就把这些配置全部改好。我现在的流程是创建一个新项目后第一件事就是打开settings.gradle把镜像仓库配置粘贴进去然后检查 Kotlin、AGP、Gradle 三者的版本兼容矩阵最后再做首次同步。这个习惯至少帮我省掉了两三次“项目搭到一半开始调依赖”的尴尬局面。团队协作的时候仓库配置最好统一到模板里。新成员入职拉代码后第一次同步就应该是顺畅的而不是第一天上班先折腾俩小时依赖。这一点体验差异直接影响新人对项目的第一印象。另外依赖版本能锁定就尽量锁定。比如 Kotlin 统一用项目根目录的plugins块声明版本子模块不要各自写死不同的 Kotlin 版本避免版本分裂带来的解析混乱。同时建议在根项目里配置统一的依赖版本目录或者使用 Version Catalog这不仅能减少依赖冲突也能在排查问题时一眼看清版本来源。5.3 我实际用下来最舒服的一套配置参考最后整一份我目前在多个项目里验证过、同步成功率明显提升的配置组合供参考Android Studio 版本Hedgehog / Iguana 以上Gradle 版本8.7 及以上AGP 版本8.4 及以上Kotlin 版本2.0.x 或 1.9.24仓库配置阿里云googlepublicgradle-plugin官方google()和mavenCentral()兜底这套组合里比较关键的是 Kotlin 2.0 和 Gradle 8.7 的配合两者在 Kotlin DSL 脚本解析和依赖解析稳定性上都有明显改进。如果项目还停留在 Kotlin 1.6、Gradle 7.x 的老组合优先考虑升级而不是继续修修补补。说实话Kotlin 依赖下载失败这件事很难通过某一个“神奇操作”彻底消失。它更像是一门需要持续维护的“卫生习惯”仓库源保持顺滑、缓存定时清理、依赖版本清晰可查、构建环境随官方迭代稳步升级。把这几个维度都照顾到虽然不能保证百分之百不报错但至少能让问题从“日常折磨”降级成“偶尔擦伤”。
Kotlin依赖下载失败？Gradle同步报错全排查指南
最近在搭一个新项目Android Studio 一点 SyncGradle 跑了不到两分钟就开始飘红Could not resolve org.jetbrains.kotlin:kotlin-stdlib:1.9.24。这种报错对 Android 开发者来说太熟悉了——Kotlin 依赖下载失败几乎每个用 Kotlin 写项目的团队都会碰到而且每次触发的原因可能都不一样。更气人的是有时候同样的配置同事那边一次过你这边就是下不下来玄学得很。这篇就把我啃过的骨头、试过的方案、总结出来的排查顺序一次性整理出来。先说清楚这不是什么高深技术就是一套实战排查手册适合刚入坑 Android 的新人也适合被 Gradle 同步折磨到怀疑人生的中级开发者甚至有人在 CI 上偶发构建失败也能从这里找到对应的解法。1. 先搞清楚Kotlin 依赖下载失败到底是什么原因1.1 别急着改配置先看报错长什么样很多人一看到依赖下载失败就条件反射去找镜像源结果改了半天还是不行。我的经验是先把报错完整读一遍不同报错指向的根因完全不一样。最常见的几类报错信息Could not resolve org.jetbrains.kotlin:kotlin-stdlib:1.9.24——这是最笼统的说法意思是 Gradle 在声明的仓库里都没找到这个依赖或者仓库源压根连不上。Could not GET https://...——这种说明 Gradle 确实尝试去某个仓库地址拉文件了但请求失败了可能是超时、连接被重置也可能是这个地址返回了错误状态码。SSLHandshakeException——证书相关的问题多半是你用了某个仓库地址但本地 Java 环境的证书链不认它。这种情况在 Android Studio 内置 JDK 版本比较老的时候特别常见。Checksum mismatch或unexpected end of archive——这不是网络问题是 Gradle 本地缓存里已经躺了一个损坏的文件下载中断、磁盘写入异常都可能造成后面专门讲缓存处理。Could not find kotlin-stdlib后面跟着一串“Searched in the following locations”——这是最有用的一种报错Gradle 会把它搜索过哪些仓库地址、找到了什么文件、缺哪个文件全都列出来。我的习惯是遇到报错先截屏或者复制完整日志不用急着查从日志里找三样东西下载失败的依赖坐标group:artifact:version、报错发生在哪个仓库、有没有缓存相关关键词。这三样定位完问题基本就缩小到一小片区域了。1.2 六个根因逐个拆开讲根据我这几年踩坑的经验Kotlin 依赖下载失败的原因可以归纳成六大类按出现频率排序第一仓库地址不可达或网络波动。这是最普遍的尤其 mavenCentral() 和 google() 这两个默认仓库服务器都在海外访问质量时好时坏。Gradle 拉依赖是串行的一个仓库连接超时要等很久才轮到下一个表现出来就是整个同步卡住然后报错。第二仓库声明顺序不对。Gradle 按照配置顺序从上往下查找依赖找到第一个包含该依赖的仓库就会停住。如果你先声明了一个速度极慢甚至不可达的仓库那每次同步都会先卡在那个仓库上。第三依赖坐标写错或者版本号不存在。常见的有把kotlin-stdlib的 group 写错、artifact 名大小写搞混、版本号打了个不存在的 tag。这种情况不管你换多少个镜像源都没用因为任何仓库里都没有这个东西。第四版本冲突与传递依赖问题。Kotlin Gradle Plugin 和 Android Gradle Plugin 之间、Kotlin 版本和协程版本之间都存在兼容矩阵有时候不是下载失败而是下载下来的版本之间互相打架导致构建中断表现却像依赖解析失败。第五本地缓存损坏。前面提到过Gradle 下载一半断网、磁盘空间不够、杀毒软件拦了文件都可能导致缓存里躺着一个坏文件。Gradle 优先使用缓存坏文件不清理问题就一直存在。第六构建环境与 Gradle 版本不匹配。Android Studio 内置的 JBRJetBrains Runtime版本、Gradle 发行版版本、AGP 版本这三个只要有一个明显偏老解析 Kotlin DSL 脚本时可能抛出奇怪异常让人误以为是依赖下载问题。这六个原因里我自己碰到最多的是一、二、五这三个加起来占了八成以上的场景。接下来的内容我会按“先网络后配置、先缓存后脚本”的顺序把每一步怎么操作、怎么验证讲透。2. 仓库配置最值得优化的一个环节2.1 为什么默认仓库会卡住新建 Android 项目的时候settings.gradle里默认写的是google()和mavenCentral()。这套配置官方推荐但实际体验就是不稳定。google()仓库的主要作用是从 Google 的 Maven 仓库拉取 AndroidX、AGP 这些构件mavenCentral()是 Sonatype 维护的 Maven 中央仓库Kotlin 标准库、协程库很多都在这里。关键在于这两个仓库的服务器都不在国内。Gradle 解析依赖的时候是同步串行请求每个仓库连接超时的时间默认是 30 秒如果某个仓库响应慢一次同步就可能拖出十几分钟。用生活类比就是你明明下楼走两步就能在便利店买到酱油非要去等一个海外代购等了一周还没到结果锅里的菜全糊了。所以想从根本上缓解下载问题第一步就是调整仓库配置把国内能稳定访问的公共镜像仓库放到最前面。注意我说的是“缓解”不是“根治”——镜像仓库再快也架不住依赖坐标写错这种主观问题。2.2 国内镜像仓库怎么选public 镜像里最常用的是阿里云的公共仓库地址是https://maven.aliyun.com/repository/public。这个仓库同步了 Maven Central 和 JCenter 的内容绝大部分开源库都能找到。Google 相关的构件比如 AndroidX、AGP、Compose需要单独用https://maven.aliyun.com/repository/google。Gradle 插件本身也有一个代理地址https://maven.aliyun.com/repository/gradle-plugin。我实测下来的组合是google public gradle-plugin三个地址覆盖日常项目的绝大部分依赖。腾讯云也有类似的镜像但阿里云这几个地址在文档、社区例子、团队协作里更通用所以优先推荐前者。还有一个容易踩的细节public里其实已经聚合了 central 和 jcenter但它不包含 google 的构件所以不要只配一个public就完事google那个一定要单独加。另外如果你的项目用了自建私服比如企业内部搭建的 Sonatype Nexus 或者 JFrog Artifactory那就在镜像源之前加上私服地址并且做好权限配置。这里不展开讲私服运维只说一点私服地址不要写在镜像仓库后面否则每次拉取外部依赖都会先去私服搜一遍如果私服本身没有做代理转发就会白白增加一次超时等待。2.3 一份可以直接抄的 settings.gradle 配置新版 Android Studio 项目统一用settings.gradle配置仓库推荐把镜像写在pluginManagement和dependencyResolutionManagement两个块里。前者管 Gradle 插件本身的下载后者管项目依赖。直接给你一份我目前最常用的配置pluginManagement { repositories { maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/gradle-plugin } maven { url https://maven.aliyun.com/repository/public } mavenCentral() google() } } dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/public } mavenCentral() google() } }注意几个关键点镜像仓库放在最前面官方仓库放在最后兜底。这样在镜像仓库能找到的依赖Gradle 根本不会去访问慢速源万一镜像仓库没有某个极其冷门的依赖兜底源还能补上。FAIL_ON_PROJECT_REPOS这个模式的含义是禁止在模块级build.gradle里再去声仓储库。以前老项目喜欢在根项目的allprojects块里写仓库配置新版本 Gradle 里这种做法会被判定为不推荐。强制统一在settings.gradle里管理好处是仓库配置只维护一份团队协作时不会出现“我本地换了镜像源你那边还是老的”这种分叉。如果项目里还有老代码在根目录build.gradle里写了类似这样的内容allprojects { repositories { maven { url https://maven.aliyun.com/repository/public } } }建议逐步迁移到settings.gradle留着也不是不能跑但可能触发RepositoriesMode.FAIL_ON_PROJECT_REPOS的报错到时候更麻烦。配置改完以后记得点一下 Android Studio 里的 “Sync Now”等它跑完看结果。如果还是报错别急接着往下看缓存和版本兼容问题。3. 本地缓存从“删了试试”到“有章可循”3.1 Gradle 缓存放哪了Gradle 把下载过的依赖缓存在本机的.gradle目录里路径按操作系统区分WindowsC:\Users\你的用户名\.gradle\caches\modules-2\files-2.1macOS / Linux~/.gradle/caches/modules-2/files-2.1在这个目录下依赖按照group/artifact/version三层目录组织。比如org.jetbrains.kotlin:kotlin-stdlib:1.9.24对应的路径就是org.jetbrains.kotlin/kotlin-stdlib/1.9.24/。这个目录里每个依赖会存下.pom、.aar、.jar、.module等文件以及一个.sha1校验文件。Gradle 再次解析到同一个依赖时优先从缓存读取只有缓存里没有或者校验失败时才会重新去远程仓库拉取。理解这个机制非常重要因为很多下载失败的“玄学”本质上是缓存里躺着一个坏文件。举一个真实案例我之前遇到一个项目androidx.core:core-ktx一直解析失败换镜像、清 Gradle 进程都试了没用。最后手动打开缓存目录发现那个版本目录下有一个.aar文件是 0 字节旁边的.part后缀文件还没合并完。这就是某次下载被中断残留的产物Gradle 校验不过反复去远程拿又反复失败。3.2 缓存损坏怎么判断判断缓存是否损坏有几个办法。看报错关键词如果报错信息里有Checksum mismatch、unexpected end of archive、No cached version available for offline mode、file not found基本都是缓存有问题。看缓存文件大小到缓存目录找到对应依赖的目录看.aar或.jar文件的大小如果明显小得离谱比如几十字节八成是坏文件。正常情况一个core-ktx的 aar 少说也有几十 KB。看有没有残留临时文件目录里出现.part、.lock后缀的文件说明之前有下载任务没正常结束。还有一种更隐蔽的情况缓存里文件本身大小正常但内容被锁或者权限不对导致 Gradle 读取失败。这个在 Windows 上偶发多半是杀毒软件实时扫描锁住了文件。3.3 安全的清理思路很多人一遇到依赖问题就删整个.gradle目录这不是不行但代价太大。删掉整个目录意味着所有项目缓存的依赖都要重新下载几百 MB 甚至几个 GB 的流量白花了而且下载过程本身就容易再次触发网络问题。我的推荐做法是精准删除关闭 Android Studio确保没有 Gradle 进程占用文件。根据报错信息找到失败的依赖坐标比如org.jetbrains.kotlin:kotlin-stdlib:1.9.24。进入缓存目录定位到org.jetbrains.kotlin/kotlin-stdlib/1.9.24/把整个版本目录删掉。重新打开项目执行 Sync。如果报错涉及多个依赖或者你懒得一个个找可以直接删除modules-2目录。这个目录只缓存依赖不影响 Gradle 本身和已有的 Wrapper 发行版删掉后所有依赖会重新下载但至少不会让你从头配置一遍环境。在 macOS/Linux 上可以直接用命令rm -rf ~/.gradle/caches/modules-2Windows 上就把C:\Users\你的用户名\.gradle\caches\modules-2这个文件夹删掉。删完以后重新同步大概率能解决缓存损坏类问题。3.4 手动装一个依赖进本地仓库的兜底方案有时候某个依赖比较冷门镜像仓库没有官方仓库又实在连不上。这种情况下有一个非常实用的兜底手段手动把依赖文件安装到本地 Maven 仓库。假设你手里有一个aar文件要从本地引入操作方法是把.aar文件放到一个临时目录比如~/Downloads/。执行 Maven 安装命令mvn install:install-file \ -Dfile~/Downloads/demo.aar \ -DgroupIdcom.example \ -DartifactIddemo \ -Dversion1.0.0 \ -Dpackagingaar项目build.gradle的依赖声明保持不变implementation com.example:demo:1.0.0同时确保仓库配置里包含mavenLocal()。mavenLocal()会优先查找本机~/.m2/repositoryWindows 是C:\Users\用户名\.m2\repository下的依赖因为我们手动执行过安装命令本地仓库里已经有了对应坐标的文件Gradle 不需要去远程拿。这个方案对于私有 SDK 集成特别有用。有些第三方 SDK 厂商给的是一个aar文件没有上传到公共 Maven 仓库又赶时间没法搭私服手动装到本地仓库就是最高效的做法。缺点也明显换一台电脑就得重新装一遍团队协作不太方便所以只能当兜底用不能当常规方案。4. 常见问题与排查技巧实录4.1 我实测遇到的 5 个高频问题把这几年帮同事排查、自己在群里答疑碰到的典型问题整理成一张速查表方便直接对照现象直接原因最快解法Kotlin 标准库下载失败但项目里其他依赖正常Kotlin 版本与仓库不同步或镜像仓库缺该版本换成稳定版 Kotlin 版本检查仓库配置顺序KGPKotlin Gradle Plugin插件下载失败插件仓库没配置对确认pluginManagement里有gradle-plugin镜像地址Android Studio 的 External Libraries 里完全没有 Maven 依赖同步没跑成功或者仓库配置在模块级不生效统一在settings.gradle配置仓库执行完整 SyncIDEA 里 Maven 依赖爆红本地仓库缓存损坏或依赖未下载重新导入项目清缓存删modules-2再同步同一个依赖第一次 Sync 成功第二次失败缓存文件损坏或网络偶发超时删除该依赖的缓存目录重新同步尤其要把第四条和第二条单拎出来说。IDEA 里 Maven 依赖爆红十次有八次是本地仓库里有坏文件剩下两次是仓库地址没生效。而 KGP 插件下载失败很多人会忽略pluginManagement这个块只改dependencyResolutionManagement结果插件还是走的海外源自然会卡。4.2 三板斧排查法如果前面那些配置都检查过了问题还没解决那就按下面这套三板斧来基本能定位九成问题。第一板斧看完整日志而不是只看 Build Output 的第一行。Android Studio 底部工具栏切到 “Build” 面板再切到 “Gradle Sync” 或者直接在终端跑./gradlew help拿完整日志。完整日志会告诉你依赖是从哪个仓库找不到的有没有缓存校验错误哪一步超时信息量完全不同。第二板斧从报错中提取下载失败的坐标然后手动在浏览器里打开对应的仓库地址。比如报错说org.jetbrains.kotlin:kotlin-stdlib:1.9.24找不到那我就在浏览器里访问https://maven.aliyun.com/repository/public/org/jetbrains/kotlin/kotlin-stdlib/1.9.24/如果这个地址能正常打开能看到.pom和.aar文件说明镜像仓库里有货问题出在 Gradle 配置或者缓存上。如果地址打不开或者找不到对应版本那就是版本号写错了或者这个仓库压根没同步这个版本。这一步能快速把“网络问题”和“配置问题”分开省去大量瞎折腾。第三板斧切离线模式验证。在 Android Studio 的 Gradle 工具窗口里勾选 “Offline Work”或者执行./gradlew --offline help如果离线模式下项目能正常解析说明所有依赖都已经在本地缓存里问题跟网络无关把注意力放到构建脚本和插件版本上。如果离线模式都失败Gradle 会明确告诉你缺哪个依赖这时候去补充镜像源或手动下载该依赖就行。4.3 排查时的几个细节习惯再分享几个我在实际排查中发现很有用的细节习惯。第一改完仓库配置以后一定要留意 Gradle 窗口里的 “Refresh” 和 “Sync” 按钮。有时候你只改了文件没点 Sync问题还挂在那但看起来像是没效果。不要以为改完文件就完事了一切以 Sync 成功为准。第二注意 Gradle 版本和 Kotlin 插件版本的兼容性。Kotlin 1.9 及以上版本对 Gradle 版本有最低要求比如 Kotlin 1.9.24 要求 Gradle 6.8.3 以上AGP 版本也有对应要求。如果你用的是特别老的 Gradle插件解析阶段就会异常表现出来还是“依赖无法下载”。遇到这种情况去官方兼容性表格核对一下版本矩阵比反复清缓存有效得多。第三项目换了电脑或者换了网络环境时如果依赖突然大面积失败先重新执行一次完整同步而不要马上删除所有缓存。我刚工作时犯过一个错误新电脑第一次同步项目因为网络慢超时了我直接删了.gradle目录结果触发了全量依赖重新下载耗时更久还额外引入了新的网络波动风险。正确的做法是重试同步等待时间拉长让 Gradle 把超时重试做完。如果连续重试三次都失败再考虑清缓存。第四如果你在公司内网开发存在自建镜像或者内网源优先用内网源不用犹豫。内网源的稳定性和速度远高于公网镜像团队统一配置也方便。5. 我的经验总结与最后的建议5.1 从依赖下载失败到稳定构建的完整操作顺序整个过程看起来步骤多但真正执行起来是可以一套组合拳打下来的。我自己现在处理 Kotlin 依赖下载失败的标准顺序是这样的完整复制报错日志提取依赖坐标和关键词。确认仓库配置重点检查settings.gradle里两个仓库块和镜像源顺序。用浏览器手动访问仓库地址确认这个依赖是否真实存在。如果依赖存在但 Gradle 拉不下来删除对应缓存目录重新同步。如果依赖不存在检查版本号是否写错或者需要升级构建工具版本。如果仍然失败切离线模式判断是不是还有未缓存的依赖再针对缺的那个单独处理。这套顺序看起来朴素但每一步都在缩小问题范围不靠运气不靠猜。5.2 把踩坑经验前置到项目初始化阶段最后说一个被反复教育之后养成的习惯不要在项目出问题的时候才开始想仓库配置而是在新建项目的第一次同步前就把这些配置全部改好。我现在的流程是创建一个新项目后第一件事就是打开settings.gradle把镜像仓库配置粘贴进去然后检查 Kotlin、AGP、Gradle 三者的版本兼容矩阵最后再做首次同步。这个习惯至少帮我省掉了两三次“项目搭到一半开始调依赖”的尴尬局面。团队协作的时候仓库配置最好统一到模板里。新成员入职拉代码后第一次同步就应该是顺畅的而不是第一天上班先折腾俩小时依赖。这一点体验差异直接影响新人对项目的第一印象。另外依赖版本能锁定就尽量锁定。比如 Kotlin 统一用项目根目录的plugins块声明版本子模块不要各自写死不同的 Kotlin 版本避免版本分裂带来的解析混乱。同时建议在根项目里配置统一的依赖版本目录或者使用 Version Catalog这不仅能减少依赖冲突也能在排查问题时一眼看清版本来源。5.3 我实际用下来最舒服的一套配置参考最后整一份我目前在多个项目里验证过、同步成功率明显提升的配置组合供参考Android Studio 版本Hedgehog / Iguana 以上Gradle 版本8.7 及以上AGP 版本8.4 及以上Kotlin 版本2.0.x 或 1.9.24仓库配置阿里云googlepublicgradle-plugin官方google()和mavenCentral()兜底这套组合里比较关键的是 Kotlin 2.0 和 Gradle 8.7 的配合两者在 Kotlin DSL 脚本解析和依赖解析稳定性上都有明显改进。如果项目还停留在 Kotlin 1.6、Gradle 7.x 的老组合优先考虑升级而不是继续修修补补。说实话Kotlin 依赖下载失败这件事很难通过某一个“神奇操作”彻底消失。它更像是一门需要持续维护的“卫生习惯”仓库源保持顺滑、缓存定时清理、依赖版本清晰可查、构建环境随官方迭代稳步升级。把这几个维度都照顾到虽然不能保证百分之百不报错但至少能让问题从“日常折磨”降级成“偶尔擦伤”。