解决Gradle依赖下载问题方案汇总在使用 Gradle 处理项目构建时，常常会出现构建需要的依赖下载失败的问题。这篇文

在使用 Gradle 处理项目构建时，常常会出现构建需要的依赖下载失败的问题。这篇文章就介绍一下如何解决这一类的问题。

Gradle 下载失败问题

在创建一个新项目或者下载一个项目时，Gradle 会根据 gradle/wrapper/gradle-wrapper.properties 文件中的 distributionUrl 属性来下载对应的 Gradle 版本。文件示例如下：

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
#下载 Gradle 8.9 的版本
distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

如果此时下载对应版本的 Gradle 失败，会提示 Connection timed out 的错误，如下图所示：

此时有三种解决方案，分别是：修改 Gradle 版本、使用镜像站点、直接下载解压缩到指定目录

方案1：修改 Gradle 版本

如果 gradle 版本没有要求，可以查看一下 C:\Users\用户名\.gradle\wrapper\dists 目录下已经下载好的版本。如下图所示：

点击进入对应版本Gradle的目录，从下图可以看到 8.2 版本的Gradle 已经下载成功了，存在 gradle-8.2目录；而 8.9版本的 Gradle 则是下载失败的，因为不存在gradle-8.9目录。

因此可以把 distributionUrl的属性改成 https\://services.gradle.org/distributions/gradle-8.2-bin.zip ，这样就可以复用之前的 gradle 版本了。

方案2：使用镜像站点

默认情况下，Gradle 会在使用 https://services.gradle.org/distributions/ 官网链接来下载对应的 Gradle 版本。当使用官网链接下载失败时，我们可以替换成镜像站点来下载，常用的镜像站点有：

腾讯云镜像 Gradle下载地址：https://mirrors.cloud.tencent.com/gradle/
阿里云镜像 Gradle下载地址：https://mirrors.aliyun.com/macports/distfiles/gradle/

示例如下：

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
// 把 distributionUrl=https\://services.gradle.org/distributions 替换成对应的站点链接
distributionUrl=https\://mirrors.aliyun.com/macports/distfiles/gradle//gradle-8.9-all.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

需要注意：镜像站点的 Gradle 更新可能不及时，因此最新版本的 Gradle 可能不存在

方案3：直接下载解压缩到指定目录

当我们使用镜像站点下载的 Gradle 版本不存在时，可以在官网 Gradle Distributions 直接下载 zip 包，并解压到 C:\Users\user\.gradle\wrapper\dists\gradle版本目录 下就可以了，如下图所示：

版本兼容问题

在开发 Android 项目时，我们需要确保 Android studio 版本、AGP版本、Gradle版本符合、kotlin 版本等符合要求。如果不符合要求，则会导致兼容问题的错误。

AGP版本在 gradle/libs.versions.toml 文件中；而 Gradle版本在gradle/wrapper/gradle-wrapper.properties 文件中。示例如下：

// gradle-wrapper.properties 文件
distributionBase=GRADLE_USER_HOME
distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-bin.zip // gradle版本号
distributionPath=wrapper/dists
zipStorePath=wrapper/dists
zipStoreBase=GRADLE_USER_HOME


// libs.versions.toml 文件
[versions]
androidGradlePlugin = "8.6.1" // agp版本号
kotlin = "1.9.22"

[plugins]
android-application = { id = "com.android.application", version.ref = "androidGradlePlugin" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

AGP 和 Gradle版本兼容问题

AGP 和 Gradle版本兼容要求如下图所示：

Android studio 版本和 AGP的兼容问题

Android studio 版本和 AGP的兼容要求如下图所示。如果需要看当前 Android studio的版本，可以通过 Help -> about 查看。

最新的兼容关系可以看官网：Android Gradle 插件 8.8 版本说明

kgp 、gradle、agp之间兼容关系问题

最新的兼容关系可以看官网：配置 Gradle 项目 · Kotlin 官方文档中文版

依赖下载失败问题

依赖下载失败的原因有很多，这里推荐按照一定的流程找出问题。下面介绍笔者开发时使用的排除流程：

第一步，使用镜像站点

依赖下载失败大部分是因为墙的限制，我们可以使用镜像站点来解决这个问题。代码示例如下，使用了阿里云的镜像站点

kts 的代码使用如下：

pluginManagement {
    repositories {
        maven { url =  uri("https://maven.aliyun.com/repository/public") }
        maven { url =  uri("https://maven.aliyun.com/repository/google") }
        maven { url =  uri("https://maven.aliyun.com/repository/jcenter") }
        maven { url =  uri("https://mirrors.aliyun.com/macports/distfiles/gradle") }
        maven { url =  uri("https://repo1.maven.org/maven2/") }
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven { url =  uri("https://maven.aliyun.com/repository/public") }
        maven { url =  uri("https://maven.aliyun.com/repository/google") }
        maven { url =  uri("https://maven.aliyun.com/repository/jcenter") }
        maven { url =  uri("https://mirrors.aliyun.com/macports/distfiles/gradle") }
        maven { url =  uri("https://repo1.maven.org/maven2/") }
        google()
        mavenCentral()
    }
}

groovy 的使用如下：

repositories {

    maven {
        url "https://maven.aliyun.com/repository/public"
    }
    maven {
        url "https://maven.aliyun.com/repository/google"
    }
    maven {
        url "https://maven.aliyun.com/repository/jcenter"
    }
    maven {
        url "https://mirrors.aliyun.com/macports/distfiles/gradle"
    }
    maven {
        url "https://repo1.maven.org/maven2/"
    }
    google()
    jcenter()
}

第二步：检查

如果配置了镜像还是有问题，这时需要先看是否配置有问题，最好是复制对照，用眼睛对照是不靠谱的。如果配置没有问题，那么就看一下当时是否为离线模式，如果是离线模式则需要修改后再次尝试。

屏幕截图 2025-01-28 152237.png

第三步：clean build

有时候，当你修改 kotlin 版本号或者插件版本号时，会导致缓存无法使用，从而构建失败。这时候可以尝试使用 clean project，然后再重试。

屏幕截图 2025-01-30 232659.png

其他问题

prepareKotlinBuildScriptModel 任务失败

打开项目目录下 gradle/wrapper/gradle-wrapper.properties，将distributionUrl结尾的-bin.zip 改为-all.zip。然后打开终端运行gradlew --stop（建议顺便重启一下Android Studio）。最后重新 sync gradle 就可以了

Your build is currently configured to use incompatible Java XXX and Gradle XXX. Cannot sync the project.

屏幕截图 2025-03-08 171105.png

如上图所示，出现这个问题是 Gradle 版本和 Java 版本不一致。需要在 setting -> Build -> Gradle 中修改 Gradle JDK 的版本就可以了

屏幕截图 2025-02-19 155154.png

解决Gradle依赖下载问题方案汇总