【Android】Gradle 又卡在 Downloading 了？一次配置，全电脑 Android 项目不再龟速下载

1. Gradle 又卡在 Downloading 了？一次配置，全电脑 Android 项目不再龟速下载
2. 每个新项目都要重新下 Gradle？其实不用——全局镜像 + 缓存一次讲透
3. assembleDebug 等了一小时还没完？国内 Android 开发者必备的全局加速方案
4. Could not resolve 报错、下载超时、构建卡死——Gradle 全局国内镜像一键解决
5. 删了 .gradle 又要从头下？先搞懂缓存机制，再配一次终身受用

** 不用每个项目改 build.gradle，30 秒配置 init.gradle，Maven / Google 依赖走国内源

建议标签： Gradle、Android、下载慢、构建失败、国内镜像、init.gradle、AndroidStudio

---

Gradle 又卡在 Downloading 了？一次配置，全电脑 Android 项目不再龟速下载

做 Android 开发的同学，大概率都经历过这种崩溃：
新建一个项目 → gradlew assembleDebug → 卡在 Downloading gradle-8.x-bin.zip 或 Could not resolve com.android.tools.build:gradle 半小时不动。

本文分享一套 Windows 下一键全局配置方案：配置一次，本机所有 Gradle / Android 项目自动走国内镜像，构建速度明显提升，而且不用每个项目改 build.gradle。

---

一、为什么你需要「全局配置」？

1.1 默认 Gradle 有多慢？

Gradle 构建时至少有两类下载：

下载内容	默认来源	国内体验
Gradle 本体（zip，~100MB）	services.gradle.org	慢，易超时
AndroidX / Google / Maven 依赖	google()、mavenCentral()	慢，甚至失败
Gradle 插件	gradlePluginPortal()	不稳定

如果你每开一个新项目、每换一个 Gradle 版本，都要重新等一遍，一天浪费几十分钟非常正常。

1.2 全局配置 vs 单项目配置

对比	每个项目改 build.gradle	全局 init.gradle
配置次数	N 个项目配 N 次	1 次，全项目生效
新项目	又要改一遍	自动生效
Flutter / RN / 原生 Android	各配各的	统一加速
维护成本	高	低
卸载	改多个文件	删 1 个 init.gradle

亮点：一次配置，终身受益（同一台电脑）。

---

二、Gradle 缓存机制（搞懂就不焦虑）

很多人以为「每个项目都要重新下载 Gradle」，其实 不是。

2.1 三层缓存，各司其职

┌─────────────────────────────────────────────────────────┐
│  ① Gradle 本体 zip（按版本）                              │
│  位置: C:\Users\你\.gradle\wrapper\dists\               │
│  规则: Gradle 8.4 只下载 1 次，所有用 8.4 的项目共用       │
├─────────────────────────────────────────────────────────┤
│  ② Maven / Google 依赖（按坐标）                          │
│  位置: C:\Users\你\.gradle\caches\                       │
│  规则: androidx.appcompat:app:1.6.1 全局只下 1 次         │
├─────────────────────────────────────────────────────────┤
│  ③ 构建产物缓存（增量编译）                                │
│  位置: C:\Users\你\.gradle\caches\build-cache-1\         │
│  规则: 开启 org.gradle.caching=true 后复用                 │
└─────────────────────────────────────────────────────────┘

重点：

• ❌ 不是「每个 Android 项目下载一份 Gradle」
• ✅ 是「每个 Gradle 版本 在本机只下载一次」
• ✅ 依赖库也是 全局共享缓存

你感觉「总在下载」，通常是：

1. 第一次用这个 Gradle 版本
2. 项目用了 不同版本（8.0 / 8.4 / 8.7 各一份）
3. 缓存被清（磁盘清理、杀毒、手删 .gradle）
4. 从国外源下载 超时失败，Gradle 反复重试

---

三、全局方案架构

我们采用 Gradle 官方支持的 用户级配置，写入用户目录，对所有项目生效：

C:\Users\你的用户名\.gradle\
├── init.gradle          ← 国内 Maven / Google 镜像（核心）
├── gradle.properties    ← daemon、并行、缓存、超时
└── wrapper\dists\       ← Gradle zip 自动缓存（无需手配）

3.1 init.gradle 做什么？

在每个项目构建开始前自动注入仓库地址，优先走：

• 阿里云 maven.aliyun.com（public / google / gradle-plugin）
• 腾讯云 mirrors.cloud.tencent.com

同时保留 google()、mavenCentral() 作为兜底，镜像没有时自动回退。

3.2 gradle.properties 做什么？

配置项	作用	亮点
org.gradle.daemon=true	守护进程	第二次构建秒启动
org.gradle.parallel=true	并行模块	多模块项目明显加速
org.gradle.caching=true	构建缓存	未改动的模块直接复用
org.gradle.configureondemand=true	按需配置	只配置参与构建的子项目
org.gradle.jvmargs=-Xmx2048m	内存	减少 OOM
connectionTimeout=180000	超时 3 分钟	慢网不会立刻判死

---

四、一键安装（推荐）

如果你在用「白猫助手 / fardriverApp」项目，已自带脚本：

:: 方式 1：双击
fardriverApp\全局Gradle镜像.bat

:: 方式 2：打包菜单里选 5
fardriverApp\打包.bat

脚本会自动：

1. 复制 init.gradle → %USERPROFILE%\.gradle\init.gradle
2. 追加加速参数 → %USERPROFILE%\.gradle\gradle.properties
3. 已配置过的不会重复写入（可重复运行）

30 秒搞定，零门槛。

---

五、手动配置（通用，任何项目可用）

不想依赖脚本，可以手动创建以下两个文件。

5.1 创建 init.gradle

路径：C:\Users\你的用户名\.gradle\init.gradle

// 全局 Gradle 国内镜像 — 对所有 Android / Gradle 项目生效

def ALIYUN_PUBLIC = 'https://maven.aliyun.com/repository/public'
def ALIYUN_GOOGLE = 'https://maven.aliyun.com/repository/google'
def ALIYUN_PLUGIN = 'https://maven.aliyun.com/repository/gradle-plugin'
def TENCENT_PUBLIC = 'https://mirrors.cloud.tencent.com/nexus/repository/maven-public'

// 新版 Android 项目（settings.gradle / .kts）
gradle.beforeSettings { settings ->
    settings.pluginManagement.repositories { repos ->
        repos.maven { url ALIYUN_PLUGIN }
        repos.maven { url ALIYUN_GOOGLE }
        repos.maven { url ALIYUN_PUBLIC }
        repos.maven { url TENCENT_PUBLIC }
        repos.gradlePluginPortal()
        repos.google()
        repos.mavenCentral()
    }
    try {
        settings.dependencyResolutionManagement.repositories { repos ->
            repos.maven { url ALIYUN_GOOGLE }
            repos.maven { url ALIYUN_PUBLIC }
            repos.maven { url TENCENT_PUBLIC }
            repos.google()
            repos.mavenCentral()
        }
    } catch (ignored) {}
}

// 旧版项目 / 子模块
allprojects { project ->
    project.buildscript.repositories { repos ->
        repos.maven { url ALIYUN_PLUGIN }
        repos.maven { url ALIYUN_GOOGLE }
        repos.maven { url ALIYUN_PUBLIC }
        repos.google()
        repos.mavenCentral()
    }
    project.repositories { repos ->
        repos.maven { url ALIYUN_GOOGLE }
        repos.maven { url ALIYUN_PUBLIC }
        repos.google()
        repos.mavenCentral()
    }
}

5.2 追加 gradle.properties

路径：C:\Users\你的用户名\.gradle\gradle.properties

org.gradle.daemon=true
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.configureondemand=true
org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
systemProp.org.gradle.internal.http.connectionTimeout=180000
systemProp.org.gradle.internal.http.socketTimeout=180000

5.3 验证是否生效

任意 Android 项目执行：

cd 你的项目\android
gradlew.bat --version
gradlew.bat assembleDebug --info

日志里应出现从 maven.aliyun.com 或 mirrors.cloud.tencent.com 拉依赖的记录。

---

六、Gradle 本体 zip 也要加速

init.gradle 管不了 Gradle Wrapper 下载 zip 的地址，那个写在每个项目的：

gradle/wrapper/gradle-wrapper.properties

建议改成腾讯云（与官方同版本）：

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

常用版本对照：

版本	腾讯云地址
8.4	https://mirrors.cloud.tencent.com/gradle/gradle-8.4-bin.zip
8.7	https://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip
8.9	https://mirrors.cloud.tencent.com/gradle/gradle-8.9-bin.zip

下载后仍缓存在 %USERPROFILE%\.gradle\wrapper\dists\，同版本全项目共用。

预下载（可选）

第一次可以提前拉进缓存，以后打包不再等：

cd 项目\android
gradlew.bat --version

或运行 fardriverApp\预下载Gradle.bat。

---

七、方案亮点总结

亮点	说明
🚀 一次配置，全项目生效	新 clone 的项目不用改 build.gradle
🌏 双镜像兜底	阿里云 + 腾讯云，一个挂另一个顶上
📦 全局依赖缓存	同一个 AAR/JAR 全电脑只下 1 次
⚡ 构建加速三件套	daemon + parallel + build cache
🔧 兼容新旧项目	同时 hook beforeSettings 和 allprojects
🛡️ 保留官方源	镜像没有包时自动走 google/mavenCentral
💾 不污染项目代码	配置在用户目录，不进 Git
♻️ 可重复执行	脚本有去重，不会无限追加
🗑️ 可一键卸载	删 init.gradle + 清理 properties 即可

---

八、效果对比（实测感受）

场景	未配置	全局镜像后
首次构建新项目	20~60 分钟（视网络）	5~15 分钟
第二次构建	3~10 分钟	30 秒 ~ 2 分钟
Gradle 8.4 已缓存后	仍可能慢（依赖从国外拉）	秒级启动 wrapper
断网重编译（依赖齐）	可能失败	可离线构建（依赖已缓存）

注：具体时间因网络、项目大小、机器性能而异，以上为常见区间。

---

九、常见问题 FAQ

Q1：配了全局镜像，为什么还在 Downloading gradle-xxx-bin.zip？

这是 Gradle 本体，不是 Maven 依赖。
每个 版本 第一次会下载，之后用缓存。
解决：改 gradle-wrapper.properties 为腾讯云 + 预跑一次 gradlew --version。

Q2：会影响团队其他人吗？

不会。 配置在你本机 %USERPROFILE%\.gradle\，不进 Git，不影响同事。

Q3：和项目里已经写的阿里云仓库冲突吗？

不冲突。镜像源优先，官方源兜底。项目里已有的配置仍然有效。

Q4：Flutter / React Native 项目能用吗？

能。 只要底层走 Gradle（Android 部分），全局 init.gradle 都生效。

Q5：怎么卸载？

del %USERPROFILE%\.gradle\init.gradle
:: gradle.properties 里删掉 org.gradle.daemon 等追加的几行

Q6：可以换别的镜像吗？

可以。把 URL 换成华为云、清华 TUNA 等，原理一样。
阿里云 + 腾讯云是目前 Android 生态覆盖较全的组合。

Q7：.gradle 文件夹可以删吗？

不建议。 删了 = 所有 Gradle 版本 + 依赖缓存全丢，下次全部重新下载。
磁盘清理工具请把 .gradle 加入白名单。

---

十、推荐工作流（Windows Android 开发者）

:: ① 一次性：全局镜像（本文方案）
全局Gradle镜像.bat

:: ② 一次性：预下载常用 Gradle 版本
cd 你的项目\android
gradlew.bat --version

:: ③ 日常打包
gradlew.bat assembleDebug
:: 或 fardriverApp\打包.bat

三句话记住：

1. 依赖镜像 → 全局 init.gradle（配一次）
2. Gradle zip → 改 wrapper 腾讯云 + 按版本缓存
3. 别删 → C:\Users\你\.gradle\ 是你的命根子

---

十一、总结

Gradle 慢，不一定是 Gradle 的锅，90% 是国内访问官方源的问题。

用 全局 init.gradle + gradle.properties 把 Maven / Google 依赖切到国内镜像，再配合 wrapper 腾讯云 + 本地缓存，是 Android 开发者性价比最高的一招：

• 不用改每个项目
• 不用搭 VPN
• 配置 5 分钟，以后每天都省时间

如果你也在 Windows 上折腾 Android 打包，强烈建议先花半分钟跑一遍全局镜像脚本，再开始 assembleDebug。

本文为 Gradle 全局加速实践总结，配置以 Gradle 8.x + Android Gradle Plugin 8.x 为参考环境。