解决Gradle下载依赖慢的问题：国内镜像源配置全攻略

你是不是也遇到过这种情况：在项目初始化或者构建时，Gradle 下载依赖库的速度慢得像蜗牛，进度条半天不动，严重拖慢了开发效率。这通常是因为默认的仓库服务器在国外，网络连接不稳定导致的。别担心，今天我们就来彻底解决这个问题，通过配置国内的镜像源，让你的 Gradle 飞起来。

一、为什么Gradle下载会慢？先了解基本原理

Gradle 在构建项目时，会根据我们配置文件中的声明，去指定的“仓库”里下载所需的库文件。默认情况下，Gradle 使用的是 Maven Central Repository 和 Google's Maven repository 等位于海外的公共仓库。由于众所周知的网络原因，从国内直接访问这些仓库，速度自然快不起来。

这就好比你想买一本进口原版书，直接从国外官网订购，邮费贵、时间长。而更聪明的做法是找国内的图书代理商或大型电商的海外购，它们已经把书囤在了国内的保税仓，你下单后很快就送到了。配置国内镜像源就是这个道理：国内的服务提供商（如阿里云、腾讯云、华为云等）将海外仓库的库文件同步到国内的服务器上，我们访问国内服务器，速度就得到了质的飞跃。

理解了这一点，我们就可以开始动手配置了。配置的核心，就是修改 Gradle 的初始化脚本或项目构建脚本，告诉它：“以后别去国外那个慢吞吞的仓库了，去国内这个快的！”

二、全局配置：一劳永逸的解决方案（推荐）

如果你有多个项目，或者不想在每个项目里都重复配置，那么全局配置是最佳选择。它会对你电脑上所有使用 Gradle 的项目生效。

技术栈：Gradle (Kotlin DSL)

我们需要找到并修改 Gradle 的全局初始化脚本文件。这个文件通常位于你的用户目录下的 .gradle 文件夹中。

操作步骤：

打开你的用户主目录（例如，Windows 是 C:\Users\你的用户名，macOS/Linux 是 /home/你的用户名 或 /Users/你的用户名）。
找到并进入 .gradle 文件夹（这是一个隐藏文件夹，你可能需要在系统设置中开启显示隐藏文件）。
在 .gradle 文件夹下，创建一个名为 init.gradle.kts 的文件（如果已存在，直接编辑它）。

接下来，我们将国内镜像源的地址配置到这个文件中。这里以配置阿里云 Maven 镜像源为例，因为它非常全面，同步也及时。

示例代码：

// 技术栈：Gradle (Kotlin DSL)
// 文件位置：~/.gradle/init.gradle.kts
// 这是一个Gradle初始化脚本，对所有项目生效

allprojects {
    // 在构建开始前，对所有项目进行仓库配置
    buildscript {
        // 配置构建脚本自身的仓库（用于下载Gradle插件等）
        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/gradle-plugin/") }
            mavenCentral() // 保留中央仓库作为备用
        }
    }

    // 配置项目本身的依赖仓库
    repositories {
        // 使用阿里云代理的公共仓库
        maven { url = uri("https://maven.aliyun.com/repository/public/") }
        // 使用阿里云代理的Google仓库（Android开发必备）
        maven { url = uri("https://maven.aliyun.com/repository/google/") }
        // 使用阿里云代理的Gradle插件仓库
        maven { url = uri("https://maven.aliyun.com/repository/gradle-plugin/") }
        // 保留Maven中央仓库，当镜像源没有所需依赖时可回退（但通常阿里云很全）
        mavenCentral()
    }
}

配置详解与注意事项：

allprojects：确保配置应用到所有子项目（如果你的项目是多模块的）。
buildscript.repositories：这部分配置影响的是 Gradle 自身需要下载的东西，比如各种构建插件（例如 com.android.application）。如果这里不配置，下载插件时依然会卡顿。
repositories：这部分配置影响的是你的项目代码所声明的依赖库（例如 implementation 'com.google.guava:guava:31.1-jre'）。
顺序很重要： Gradle 会按顺序检查仓库。我们把速度最快的阿里云镜像放在前面，这样 Gradle 会优先从那里下载。如果镜像源没有某个特定的库（这种情况极少），它才会继续检查后面的 mavenCentral()。
保留默认仓库：建议保留 mavenCentral() 作为最后一个选项，这是一个良好的备份策略。

保存这个文件后，重启你的IDE（如 IntelliJ IDEA 或 Android Studio）或命令行终端，然后重新尝试同步或构建项目，你应该能立刻感受到速度的提升。

三、单项目配置：灵活控制的备选方案

如果你只想对某个特定项目生效，或者没有权限修改全局配置，可以在项目级的构建脚本中进行配置。

技术栈：Gradle (Kotlin DSL)

我们需要修改项目根目录下的 build.gradle.kts 文件（对于 Gradle 7.0 及以上版本，如果是 Groovy DSL 则是 build.gradle）。

示例代码：

// 技术栈：Gradle (Kotlin DSL)
// 文件位置：项目根目录 / build.gradle.kts

// 1. 首先，在构建脚本部分配置插件下载源
buildscript {
    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/gradle-plugin/") }
        mavenCentral()
    }
    dependencies {
        // 这里是你项目所需的Gradle插件依赖
        classpath("com.android.tools.build:gradle:7.4.2")
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.10")
    }
}

// 2. 使用 allprojects 或 subprojects 为所有（子）模块配置依赖源
allprojects {
    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/central/") } // 阿里云中央仓库镜像
        mavenCentral()
        // 如果你还有其他特定仓库，也可以在这里添加
        // maven { url = uri("https://jitpack.io") } // 例如 JitPack
    }
}

关联技术：Gradle Wrapper 有时，即使配置了镜像，第一次使用 ./gradlew 命令时，下载 Gradle 发行版（Wrapper）本身还是很慢。这时可以配置 Wrapper 的下载镜像。修改项目根目录下的 gradle/wrapper/gradle-wrapper.properties 文件：

# 文件位置：项目根目录 / gradle/wrapper/gradle-wrapper.properties
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.0-bin.zip
# 将上面的 `mirrors.cloud.tencent.com` 替换为国内镜像站地址
# 例如阿里云：https://mirrors.aliyun.com/gradle/gradle-8.0-bin.zip
# 例如华为云：https://mirrors.huaweicloud.com/gradle/gradle-8.0-bin.zip

四、其他国内主流镜像源推荐与选择

除了阿里云，国内还有很多优秀的公共服务提供商提供了 Maven 镜像。你可以根据网络情况选择最适合你的一个。

1. 腾讯云镜像：

地址：https://mirrors.cloud.tencent.com/nexus/repository/maven-public/
特点：速度稳定，同步及时。

2. 华为云镜像：

地址：https://mirrors.huaweicloud.com/repository/maven/
特点：同样覆盖全面，对于华为云用户可能网络更优。

3. 网易镜像：

地址：http://mirrors.163.com/maven/repository/maven-public/ (注意是HTTP)
特点：老牌镜像站。

4. 中国科学技术大学镜像：

地址：https://mirrors.ustc.edu.cn/nexus/content/repositories/
地址（简化公共库）：https://mirrors.ustc.edu.cn/repository/maven/
特点：高校维护，公益性质，非常可靠。

如何选择？ 你可以简单地把你配置中的阿里云地址替换成上述任何一个地址。如果某个镜像源偶尔不稳定，可以尝试换另一个。你甚至可以在 repositories 块中同时配置多个镜像源，Gradle 会按顺序尝试。

五、应用场景、优缺点与注意事项

应用场景：

任何在国内使用 Gradle 进行项目构建的开发者，无论是 Java、Kotlin 还是 Android 项目。
团队协作时，统一镜像源配置可以保证所有成员构建环境一致，避免因网络差异导致依赖下载失败。
在持续集成/持续部署（CI/CD）环境中，配置国内镜像可以显著缩短构建流水线的执行时间。

技术优缺点：

优点：
- 速度飞跃：最直接的收益，依赖下载时间从几分钟甚至几十分钟缩短到几秒或几十秒。
- 提升稳定性：避免了因国际网络波动造成的构建失败。
- 配置简单：只需修改一个配置文件，成本极低。
- 无副作用：镜像内容与源仓库保持一致，不会影响依赖的正确性。
缺点：
- 轻微延迟：镜像同步源仓库会有一定的时间差（通常是几小时到一天），对于极少数刚刚发布的最新版本库，可能无法立即从镜像获取。此时可以临时注释掉镜像，使用原始仓库，或等待几小时后再试。
- 镜像站可靠性：虽然主流镜像站都很稳定，但理论上存在服务不可用的风险。因此配置备用仓库（如原 mavenCentral()）是好的实践。

重要注意事项：

清理缓存：修改配置后，如果速度没有改善，可以尝试清理 Gradle 缓存。在命令行运行 ./gradlew cleanBuildCache 或直接删除 ~/.gradle/caches 目录（更彻底，但下次构建需要重新下载所有依赖）。
IDE 重启：修改全局配置 (init.gradle) 后，必须重启 IDE 才能生效，因为 IDE 内部会缓存 Gradle 的运行时环境。
网络环境：确保你的开发机网络可以正常访问你选择的国内镜像站地址。有些公司内网可能有特殊策略。
安全考量：只使用信誉良好的大型公共镜像站。对于涉及敏感信息的私有依赖，应使用公司内部的私有仓库（如 Nexus、Artifactory），并正确配置其认证信息。

六、总结

通过为 Gradle 配置国内镜像源，我们巧妙地绕开了国际网络的瓶颈，将依赖下载的体验从“痛苦等待”提升到“瞬间完成”。无论是采用全局的一劳永逸法，还是针对单个项目的灵活配置，其核心思路都是将仓库地址指向国内的镜像服务器。

记住关键步骤：找到正确的配置文件（全局的 init.gradle.kts 或项目内的 build.gradle.kts），在 buildscript 和普通 repositories 两部分都添加镜像地址，并将其顺序排在默认仓库之前。同时，别忘了 Gradle Wrapper 的下载地址也可以配置镜像。

希望这篇攻略能帮助你彻底告别 Gradle 下载慢的烦恼，让你能更专注于代码逻辑本身，享受流畅高效的开发过程。现在就动手试试吧！

敲码拾光专注于编程技术，涵盖编程语言、代码实战案例、软件开发技巧、IT前沿技术、编程开发工具，是您提升技术能力的优质网络平台。