实战：2024年Gradle全局镜像加速配置全攻略

1. 为什么需要Gradle全局镜像加速如果你经常使用Gradle构建项目一定遇到过依赖下载慢甚至失败的情况。这是因为Gradle默认从国外的Maven中央仓库和Google仓库下载依赖对于国内开发者来说网络延迟和稳定性都是大问题。我曾经在一个新项目初始化时光是下载依赖就花了2个多小时期间还失败了3次这种体验实在太糟糕了。全局镜像加速的核心思路很简单把Gradle默认访问的国外仓库地址替换成国内的镜像站点。国内主流云服务商都提供了Maven镜像服务比如阿里云、腾讯云、华为云等。这些镜像会定期同步国外的仓库内容我们在国内访问速度能提升10倍以上。2. 环境准备与基础配置2.1 安装Gradle首先确保你已经安装了Gradle。推荐使用最新稳定版目前是8.8安装步骤很简单从Gradle官网下载对应平台的二进制包解压到你喜欢的目录比如/opt/gradle-8.8或D:\dev\gradle-8.8配置环境变量GRADLE_HOME指向解压目录把$GRADLE_HOME/bin添加到PATH中验证安装是否成功gradle -v2.2 配置Gradle缓存目录可选Gradle默认会把下载的依赖缓存到用户目录下的.gradle文件夹。如果你C盘空间紧张可以通过环境变量修改这个位置# Windows setx GRADLE_USER_HOME D:\gradleRepository # macOS/Linux export GRADLE_USER_HOME/opt/gradleRepository3. 配置全局镜像加速3.1 理解init.gradle的作用init.gradle是Gradle的初始化脚本会在每个项目构建前自动执行。我们可以利用它来全局替换仓库地址。这个文件需要放在GRADLE_USER_HOME目录下默认是~/.gradle。3.2 编写init.gradle脚本下面是一个完整的配置示例替换了所有主流仓库为阿里云镜像allprojects { repositories { def ALIYUN_REPOSITORY_URL https://maven.aliyun.com/repository/public def ALIYUN_JCENTER_URL https://maven.aliyun.com/repository/public def ALIYUN_GOOGLE_URL https://maven.aliyun.com/repository/google def ALIYUN_GRADLE_PLUGIN_URL https://maven.aliyun.com/repository/gradle-plugin all { ArtifactRepository repo - if(repo instanceof MavenArtifactRepository){ def url repo.url.toString() if (url.startsWith(https://repo1.maven.org/maven2/)) { project.logger.lifecycle Repository ${repo.url} replaced by $ALIYUN_REPOSITORY_URL. remove repo } if (url.startsWith(https://jcenter.bintray.com/)) { project.logger.lifecycle Repository ${repo.url} replaced by $ALIYUN_JCENTER_URL. remove repo } if (url.startsWith(https://dl.google.com/dl/android/maven2/)) { project.logger.lifecycle Repository ${repo.url} replaced by $ALIYUN_GOOGLE_URL. remove repo } if (url.startsWith(https://plugins.gradle.org/m2/)) { project.logger.lifecycle Repository ${repo.url} replaced by $ALIYUN_GRADLE_PLUGIN_URL. remove repo } } } maven { url ALIYUN_REPOSITORY_URL } maven { url ALIYUN_JCENTER_URL } maven { url ALIYUN_GOOGLE_URL } maven { url ALIYUN_GRADLE_PLUGIN_URL } } }这个脚本做了以下几件事定义了阿里云各个镜像仓库的地址遍历所有仓库识别出需要替换的官方仓库用对应的镜像地址替换掉官方仓库4. IDE集成配置4.1 IntelliJ IDEA/Android Studio配置虽然全局配置已经生效但为了确保IDE构建时也使用镜像建议在IDE设置中打开设置 - Build Tools - Gradle确保Use Gradle from选择的是gradle-wrapper.properties file在Gradle user home中指定你的GRADLE_USER_HOME路径4.2 验证配置是否生效新建一个简单的Gradle项目执行构建时观察日志输出。你应该能看到类似这样的提示Repository https://repo1.maven.org/maven2/ replaced by https://maven.aliyun.com/repository/public.也可以在构建完成后检查~/.gradle/caches/modules-2/files-2.1目录看依赖是否正常下载。5. 常见问题排查5.1 镜像同步延迟问题国内镜像通常会有几小时到一天的同步延迟。如果你需要最新的依赖版本但镜像还未同步可以临时添加官方仓库maven { url ALIYUN_REPOSITORY_URL url https://repo1.maven.org/maven2/ allowInsecureProtocol true }5.2 特殊仓库配置有些公司内部或特殊依赖可能需要额外的仓库配置。可以在项目的build.gradle中额外添加repositories { maven { url https://custom.repo.example.com } }5.3 代理设置仅限企业内网环境如果你在公司内网需要配置代理可以在gradle.properties中添加systemProp.http.proxyHostproxy.example.com systemProp.http.proxyPort8080 systemProp.https.proxyHostproxy.example.com systemProp.https.proxyPort80806. 其他镜像源选择除了阿里云国内还有其他可靠的镜像源可以选择腾讯云镜像https://mirrors.cloud.tencent.com/nexus/repository/maven-public/华为云镜像https://repo.huaweicloud.com/repository/maven/网易镜像https://mirrors.163.com/maven/repository/maven-public/替换时只需修改init.gradle中的URL即可。我个人的经验是阿里云的同步速度和稳定性最好但你可以根据实际网络情况选择最适合的镜像。