Gradle 镜像配置完全指南：从单项目到全局优化

第一章：为什么需要配置镜像？

1.1 默认配置的痛点

Gradle 默认从以下仓库下载依赖：

仓库	默认地址	问题
Maven Central	https://repo1.maven.org/maven2/	海外服务器，国内访问慢
Google	https://dl.google.com/dl/android/maven2/	间歇性无法访问
JCenter	https://jcenter.bintray.com/	已停止服务（2022年关闭）
Gradle Plugin	https://plugins.gradle.org/m2/	海外服务器，下载插件慢

典型症状：构建时卡在 Downloading...、连接超时、依赖解析失败。

1.2 阿里云镜像的优势

阿里云提供了完整的 Maven 仓库镜像服务，覆盖主流仓库：

---

第二章：单项目配置（不推荐）

2.1 配置方法

在项目的 build.gradle 中修改仓库配置：

// 项目级 build.gradle（注意：不是 app/build.gradle）
buildscript {
    repositories {
        // ❌ 原配置存在空格问题：url 'https://maven.aliyun.com/repository/google/ '
        // ✅ 修正后：去除 URL 末尾空格
        maven { url 'https://maven.aliyun.com/repository/google/' }
        maven { url 'https://maven.aliyun.com/repository/jcenter/' }
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:8.2.0'
    }
}

allprojects {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/google/' }
        maven { url 'https://maven.aliyun.com/repository/jcenter/' }
    }
}

2.2 为什么不推荐？

关键缺陷：单项目配置只能覆盖 buildscript 和 allprojects 块，无法覆盖 Gradle 插件仓库（plugins.gradle.org），导致插件下载仍然走海外。

---

第三章：全局配置（推荐方案）

3.1 配置文件位置

根据操作系统找到 Gradle 用户目录：

操作系统	路径
Windows	C:\Users\<用户名>\.gradle\
macOS	~/.gradle/
Linux	~/.gradle/

注意：<用户名> 是你的系统登录名，不一定是 Administrator。

3.2 创建 init.gradle 文件

在 .gradle 目录下新建 init.gradle 文件，使用以下配置：

allprojects {
    repositories {
        // 定义阿里云镜像地址
        def ALIYUN_REPOSITORY_URL = 'https://maven.aliyun.com/repository/public/'
        def ALIYUN_JCENTER_URL = 'https://maven.aliyun.com/repository/jcenter/'
        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()
                
                // 替换 Maven Central
                if (url.startsWith('https://repo1.maven.org/maven2/')) {
                    project.logger.lifecycle "Repository ${repo.url} replaced by $ALIYUN_REPOSITORY_URL."
                    remove repo
                }
                // 替换 JCenter（已废弃，但兼容旧项目）
                if (url.startsWith('https://jcenter.bintray.com/')) {
                    project.logger.lifecycle "Repository ${repo.url} replaced by $ALIYUN_JCENTER_URL."
                    remove repo
                }
                // 替换 Google 仓库
                if (url.startsWith('https://dl.google.com/dl/android/maven2/')) {
                    project.logger.lifecycle "Repository ${repo.url} replaced by $ALIYUN_GOOGLE_URL."
                    remove repo
                }
                // 替换 Gradle 插件仓库 ⭐ 关键优化
                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_GOOGLE_URL }            // Android 专用
        maven { url ALIYUN_GRADLE_PLUGIN_URL }    // Gradle 插件
        maven { url ALIYUN_JCENTER_URL }          // 兼容旧项目
    }
}

3.3 配置原理详解

核心机制：

1. Gradle 生命周期：init.gradle 在任何项目构建之前执行
2. 动态替换：通过遍历 repositories 列表，识别并替换海外仓库 URL
3. 优先级控制：阿里云仓库按顺序添加，确保依赖解析效率

3.4 关键修正说明

原配置问题	修正方案	影响
URL 末尾带空格 'https://.../ '	去除空格 'https://.../'	空格会导致 URL 解析失败
缺少 gradle-plugin 仓库替换	添加 plugins.gradle.org 替换逻辑	插件下载仍然走海外
使用 public 仓库覆盖所有	保留细分仓库（google/jcenter）	确保 Android 依赖正确解析

---

第四章：验证与优化

4.1 验证配置生效

执行构建命令，观察日志输出：

./gradlew build --info | grep "replaced by"

预期输出：

Repository https://repo1.maven.org/maven2/ replaced by https://maven.aliyun.com/repository/public/.
Repository https://dl.google.com/dl/android/maven2/ replaced by https://maven.aliyun.com/repository/google/.

4.2 现代项目的额外优化（Gradle 7.0+）

对于使用 plugins {} 语法的新项目，建议同时配置 settings.gradle：

// settings.gradle（项目根目录）
pluginManagement {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin/' }
        maven { url 'https://maven.aliyun.com/repository/public/' }
        gradlePluginPortal()  // 兜底，但已被 init.gradle 替换
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven { url 'https://maven.aliyun.com/repository/public/' }
        maven { url 'https://maven.aliyun.com/repository/google/' }
        mavenCentral()  // 已被 init.gradle 替换
    }
}

4.3 镜像选择策略

---

第五章：常见问题排查

问题现象	可能原因	解决方案
替换日志未出现	init.gradle 位置错误	确认放在 用户目录 下的 .gradle/，非项目目录
仍然下载慢	公司网络限制	配置 HTTP 代理或切换其他镜像（腾讯云、华为云）
特定依赖找不到	阿里云镜像同步延迟	临时添加 mavenCentral() 作为 fallback
Android 项目构建失败	Google 仓库未正确替换	检查 settings.gradle 中是否配置了 pluginManagement

---

总结

1. 单项目配置 仅作为临时方案，无法覆盖插件仓库，且维护成本高
2. 全局配置（init.gradle） 是最佳实践，通过动态替换机制确保所有依赖走阿里云镜像
3. 关键修正：去除 URL 空格、添加 gradle-plugin 替换、保留细分仓库确保兼容性
4. 现代项目 建议配合 settings.gradle 的 pluginManagement 实现双重保障

配置完成后，首次构建可能仍需下载索引，后续构建速度将显著提升（通常从几分钟缩短至几十秒）。