Android 深度实践

Appearance

国内下载加速 (Mirrors) ​

在开发 Android 应用时，Gradle 经常需要下载大量的依赖库和 Gradle 发行版。由于网络环境原因，直接连接 Google 或 Maven Central 可能会导致下载极其缓慢甚至失败。

1. 环境变量配置 (GRADLE_USER_HOME) ​

默认情况下，Gradle 的缓存、下载的依赖库和编译索引存放在用户目录下的 .gradle 文件夹中（Windows 通常在 C:\Users\用户名\.gradle）。

磁盘空间优化

由于依赖缓存占用空间非常大（动辄数 GB），强烈建议将其移出 C 盘。

配置步骤：

  1. 在非系统盘新建目录，例如 D:\env\.gradle。
  2. 在系统环境变量中新建：
    • 变量名：GRADLE_USER_HOME
    • 变量值：D:\env\.gradle
  3. 重启 IDE 或命令行生效。

2. 全局初始化脚本 (推荐方案) ​

通过在 GRADLE_USER_HOME 目录下创建 init.gradle.kts 脚本，我们可以全局拦截所有项目的仓库配置，将其重定向到国内镜像源。这种方式无需修改项目代码，且对所有项目生效。

实现步骤 ​

  1. 进入你的 GRADLE_USER_HOME 目录。
  2. 新建文件 init.gradle.kts。
  3. 填入以下内容：
kotlin
// 定义镜像映射表
private val repoMaps = mapOf(
    "ALI" to mapOf(
        "https://repo.maven.apache.org/maven2" to "https://maven.aliyun.com/repository/public/",
        "https://dl.google.com/dl/android/maven2" to "https://maven.aliyun.com/repository/google/",
        "https://plugins.gradle.org/m2" to "https://maven.aliyun.com/repository/gradle-plugin/"
    ),
    "TENCENT" to mapOf(
        "https://repo1.maven.apache.org/maven2" to "https://mirrors.tencent.com/nexus/repository/maven-public/",
        "https://repo.maven.apache.org/maven2" to "https://mirrors.tencent.com/nexus/repository/maven-public/",
        "https://dl.google.com/dl/android/maven2" to "https://mirrors.tencent.com/nexus/repository/google/"
    )
)

/**
 * 建议优先使用 TENCENT (腾讯) 镜像，通常速度更稳，库同步更及时。
 */
val selectedMirror = "TENCENT" 
val repoMap = repoMaps[selectedMirror] ?: emptyMap()

fun RepositoryHandler.enableMirror() {
    all {
        if (this is MavenArtifactRepository) {
            val originalUrl = this.url.toString().removeSuffix("/")
            repoMap[originalUrl]?.also { mirrorUrl ->
                logger.lifecycle("Mirroring: [$url] -> [$mirrorUrl]")
                this.setUrl(mirrorUrl)
            }
        }
    }
}

// 拦截初始化、配置和项目执行阶段的仓库设置
gradle.beforeSettings {
    pluginManagement.repositories.enableMirror()
    @Suppress("UnstableApiUsage")
    dependencyResolutionManagement.repositories.enableMirror()
}

gradle.allprojects {
    buildscript {
        repositories.enableMirror()
    }
    repositories.enableMirror()
}

3. Gradle 发行版下载加速 ​

上面的脚本只能加速“依赖库（Jar/AAR）”的下载。如果你在新建项目或升级 Gradle 版本时卡在 Downloading https://services.gradle.org/distributions/gradle-x.x-all.zip，则需要单独修改项目的 Wrapper 配置。

修改文件： 项目根目录/gradle/wrapper/gradle-wrapper.properties

properties
# 将官方链接替换为腾讯镜像链接
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.7-all.zip
properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-all.zip

注意

此配置是项目级别的，目前无法通过全局脚本拦截，每个新项目若下载过慢均需手动修改一次。

4. 常见国内镜像源地址 ​

组织仓库名称镜像地址
腾讯云Maven Publichttps://mirrors.tencent.com/nexus/repository/maven-public/
阿里云Publichttps://maven.aliyun.com/repository/public
阿里云Googlehttps://maven.aliyun.com/repository/google
华为云Mavenhttps://repo.huaweicloud.com/repository/maven/