3、Gradle 同步失败：网络超时、依赖仓库不可达、代理配置错误、`.gradle` 缓存损坏修复

Gradle 同步失败排查流程 Gradle 同步失败 🌐 网络超时 🏢 仓库不可达 🔧 代理配置错误 🗑️ 缓存损坏 检查网络 / 换镜像仓库 配置阿里云 / 腾讯云镜像 校验 gradle.properties 代理 删除 .gradle 缓存 ✅ 同步成功 💡 排查口诀 网络不通换镜像，代理不对看配置，缓存坏了直接删，仓库地址要核准。 先看错误日志第一行，定位是 IO 异常还是仓库 404，再对症下药。

3.1 网络超时——最常遇到的“假死”

Gradle 同步时卡在“Downloading...”十几分钟不动，十有八九是网络超时。国内开发者尤其头疼——Gradle 默认连的是 mavenCentral、jcenter、google()，这些服务器在国外，动不动就丢包。

我自己的做法是：第一时间切换到国内镜像。记得有一次项目组新同事拉下代码，同步了半小时还没完，气得差点砸电脑。我过去一看，就是没配镜像。

治本方案：在项目根目录 build.gradle（Project 级别）的 repositories 中替换为阿里云镜像：

buildscript {
    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' }
    }
}
allprojects {
    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' }
    }
}

如果全局都有这个问题，我建议改 ~/.gradle/init.gradle 文件，一劳永逸。嗯，这里要注意：这个文件默认不存在，需要手动创建。

3.2 依赖仓库不可达——不是所有 404 都是代码问题

错误日志里出现 Could not resolve artifact，很多人第一反应是去翻 dependencies 有没有写错。其实有可能是仓库本身挂掉了，或者私有仓库的地址变了。

我曾遇到一个坑：公司内部私服迁移后改了端口号，但没人通知，我以为是 AGP 版本不兼容。查了整整两个小时，后来才看到 Gradle 的报错里写着 Connection refused 才知道是仓库地址不对。

  • 步骤一：看看报错里是哪个仓库（google / mavenCentral / 自定义）
  • 步骤二：手动用浏览器打开该 URL 测试——能打开说明仓库正常，否则走镜像或联系管理员
  • 步骤三：如果是私有仓库，检查 build.gradle 中的 credentials 是否有误

一个小技巧：在 repositories 里可以同时配置多个镜像，Gradle 会按顺序尝试，第一个失败的会自动跳到下一个：

repositories {
    maven { url "https://maven.aliyun.com/repository/public" }
    maven { url "https://jitpack.io" }
    google()
}

3.3 代理配置错误——公司网络的日常

很多公司内网需要走 HTTP 代理才能访问外网。如果 gradle.properties 里配错了代理地址或者没配，Gradle 就会一直连不上仓库。错误往往表现为 Connect to repo1.maven.org:443 [repo1.maven.org/xxx] failed: Connection refused。

我曾经把代理的端口号 8080 写成了 808，愣是查了半小时才知道是笔误。你想想看，这种低级错误真的很容易忽略。

注意：代理配置在以下三个文件中都可能存在优先级冲突：

  1. 项目级 gradle.properties
  2. 用户级 ~/.gradle/gradle.properties
  3. 系统环境变量 HTTP_PROXY / HTTPS_PROXY

建议统一在 ~/.gradle/gradle.properties 中配置：

systemProp.http.proxyHost=proxy.company.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.company.com
systemProp.https.proxyPort=8080
systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.local

若你用的是 SOCKS 代理，别忘了加上 socksProxyHost 等配置。另外，代理密码如果含有特殊字符，需要用 \ 转义，这个很多人不知道。

3.4 .gradle 缓存损坏——有时候无脑删反而最快

Gradle 会在 ~/.gradle/caches 下载并缓存依赖。如果缓存文件损坏（比如下载了一半被中断、磁盘写入异常），下次同步时会报 Checksum mismatch 或者奇怪的 ZipException。

我记得有一次，项目一直报 Could not expand ZIP，怎么查都查不出原因。最后我干脆把 ~/.gradle/caches 整个删了，重新同步——居然就好了。说白了，这招就叫“重启大法”的 Gradle 版。

推荐操作：

  1. 关掉 Android Studio 和所有 Gradle 进程
  2. 删除 ~/.gradle/caches 目录（或者只删 caches/modules-2）
  3. 重新运行 ./gradlew clean 或直接打开 AS 触发同步

如果你只是想清理某个特定依赖，可以找到缓存下对应的 jar 文件手动删掉。

进阶技巧：使用 ./gradlew --refresh-dependencies 可以强制让 Gradle 重新校验所有依赖的 checksum，而不用删缓存的全部内容。对于单次修复很方便。

3.5 综合排查——一张表搞定

在实际项目中，以上四种问题经常同时出现。我个人习惯按下面的顺序排查，能省下不少时间：

错误症状 最可能原因 优先操作
长时间卡在“Downloading” 网络超时 / 仓库不可达 配置国内镜像仓库
报错“Could not resolve artifact” + 完整 URL 仓库 URL 失效或权限错误 用浏览器测试 URL，检查仓库配置
报错“Connection refused” + IP 端口 代理配置错误 检查 gradle.properties 代理设置
报错“Checksum mismatch” / “ZipException” .gradle 缓存损坏 删除 caches 目录或执行 --refresh-dependencies
同步成功但编译时缺类 依赖版本冲突或缓存脏数据 ./gradlew clean + 删除 .gradle 后重试

嗯，这里要补充一句：千万不要在没看日志的情况下无脑删缓存。先翻到 Build Output 最上面的报错信息，确认是哪个环节出了问题。我曾经见过有人每次同步失败就删整个 ~/.gradle，结果浪费了半小时下载全部依赖，其实只是代理少打了个字母。

3.6 最后一个小建议

我个人习惯在团队项目里把 gradle.properties 和 buildscript 的仓库配置写成一个公共模板，新人拉代码后直接同步，很少再出网络问题。另外，遇到顽固的缓存问题，直接 rm -rf ~/.gradle/caches 其实是最快的——你想想看，现在带宽这么宽，重新下载也就两分钟，比在那 debug 半天强多了。

如果以上方法都试过了还是不行，试试换个网络环境（比如手机热点），排除公司防火墙的干扰。毕竟，有些问题真的不是 AGP 的锅，是网络本身就不给力。

← 上一章 📖 返回目录 下一章 →