Android Studio 镜像加速 Gradle 下载

在国内使用 Android Studio 新建或导入项目时，经常会卡在 Gradle 同步阶段，例如：

1
Downloading Gradle...
2
Gradle sync failed
3
Connection timed out
4
Could not resolve...

这类问题很多时候不是项目代码错了，而是 Gradle 本体、Android Gradle Plugin、Kotlin 插件、Maven 依赖需要从国外仓库下载。网络不稳定时，同步就会非常慢，甚至直接失败。

解决思路很简单：把 Gradle 下载地址和 Maven 依赖仓库换成国内镜像。

先分清两类下载#

Android 项目构建时主要有两类下载：

Gradle 本体

由 gradle/wrapper/gradle-wrapper.properties 里的 distributionUrl 控制。
插件和项目依赖

由 settings.gradle 或 settings.gradle.kts 里的 repositories 控制，例如 Android Gradle Plugin、Kotlin 插件、第三方库等。

只改其中一个，项目仍然可能卡住。建议两个都配置。

加速 Gradle 本体下载#

打开项目里的文件：

1
gradle/wrapper/gradle-wrapper.properties

找到类似配置：

1
distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip

可以改成阿里云镜像：

1
distributionUrl=https\://mirrors.aliyun.com/gradle/gradle-8.7-bin.zip

也可以改成腾讯云镜像：

1
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip

注意：不要顺手改 Gradle 版本号。原来是 gradle-8.7-bin.zip，镜像地址里也应该保持同一个文件名。

如果镜像站没有对应版本，就换回官方地址，或者去镜像站列表里确认该版本是否存在。

加速插件和依赖下载#

新版本 Android 项目通常在 settings.gradle.kts 中配置仓库。

Kotlin DSL 示例：

1
pluginManagement {
2
    repositories {
3
        maven { url = uri("https://maven.aliyun.com/repository/google") }
4
        maven { url = uri("https://maven.aliyun.com/repository/gradle-plugin") }
5
        maven { url = uri("https://maven.aliyun.com/repository/public") }
6

7
        google()
8
        mavenCentral()
9
        gradlePluginPortal()
10
    }
11
}
12

13
dependencyResolutionManagement {
14
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
15
    repositories {
16
        maven { url = uri("https://maven.aliyun.com/repository/google") }
17
        maven { url = uri("https://maven.aliyun.com/repository/public") }
18

19
        google()
20
        mavenCentral()
21
    }
22
}
23

24
rootProject.name = "YourProject"
25
include(":app")

如果你的项目还是 Groovy 写法，settings.gradle 可以这样写：

1
pluginManagement {
2
    repositories {
3
        maven { url 'https://maven.aliyun.com/repository/google' }
4
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
5
        maven { url 'https://maven.aliyun.com/repository/public' }
6

7
        google()
8
        mavenCentral()
9
        gradlePluginPortal()
10
    }
11
}
12

13
dependencyResolutionManagement {
14
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
15
    repositories {
16
        maven { url 'https://maven.aliyun.com/repository/google' }
17
        maven { url 'https://maven.aliyun.com/repository/public' }
18

19
        google()
20
        mavenCentral()
21
    }
22
}

这里建议保留 google()、mavenCentral() 和 gradlePluginPortal() 作为兜底。镜像仓库放前面，官方仓库放后面，既能加速，也能避免镜像同步不及时导致依赖找不到。

重新同步项目#

配置完成后，在 Android Studio 中点击：

1
File -> Sync Project with Gradle Files

也可以在终端执行：

1
./gradlew --refresh-dependencies

如果之前下载失败过，可以删除 Gradle Wrapper 缓存后重试：

1
rm -rf ~/.gradle/wrapper/dists

Windows 用户对应目录通常在：

1
C:\Users\你的用户名\.gradle\wrapper\dists

常见问题#

1. 镜像地址改了还是下载失败#

先确认镜像站里有没有对应的 Gradle 版本。比如项目需要 gradle-8.7-bin.zip，镜像站也必须存在这个文件。

2. 依赖仍然从国外下载#

检查项目里是否还有旧的 build.gradle 仓库配置，或者某些模块单独写了 repositories。新项目建议统一放在 settings.gradle 或 settings.gradle.kts。

3. Android Studio 一直离线#

检查 Gradle 是否开启了离线模式：

1
Settings -> Build, Execution, Deployment -> Gradle

如果开启了 Offline work，首次下载依赖时需要先关闭。

4. 公司网络或代理影响下载#

如果你配置了代理，确认 Android Studio 和 Gradle 使用的是同一套网络设置。代理不可用时，即使配置了镜像也可能失败。

总结#

Android Studio 的 Gradle 下载慢，通常分两步处理：

修改 gradle-wrapper.properties，加速 Gradle 本体下载。
修改 settings.gradle 或 settings.gradle.kts，加速插件和依赖下载。

这两个地方都配置好后，大多数 Gradle 同步慢、依赖下载超时的问题都能解决。