【Android】 Gradle 下载后本地使用方式（macOS / Windows通用）

一、背景与原因

在 Android Studio 构建项目时，Gradle 是核心的构建工具。

默认情况下，项目在第一次构建时会自动从 Gradle 官方仓库（services.gradle.org） 下载对应版本的分发包（如 gradle-6.7.1-all.zip）。

但在以下场景下，经常需要手动下载并使用本地 Gradle 包：

📴 网络受限或内网环境（无法访问外网 Gradle 源）
⚡ 想加快构建速度（避免每台电脑重复下载）
🧩 离线构建或持续集成（CI）环境
🔒 生产环境需固定 Gradle 版本以确保一致性

因此，我们可以通过手动下载 Gradle zip 并配置为本地使用的方式，让 Android Studio 离线构建项目。

二、Gradle 分发包类型

Gradle 官方提供两种分发包：

文件名	内容	适用场景
`gradle-x.x.x-bin.zip`	仅包含运行所需的二进制文件	最小化环境部署
`gradle-x.x.x-all.zip`	包含源码、文档、API、示例等	✅ 推荐 Android Studio 使用

下载地址（以 6.7.1 为例）：
https://services.gradle.org/distributions/gradle-6.7.1-all.zip

三、操作步骤

1️⃣ 放置目录

Gradle 默认缓存目录：

系统	路径
macOS / Linux	`/Users/<用户名>/.gradle/wrapper/dists/`
Windows	`C:\Users\<用户名>\.gradle\wrapper\dists\`

每个版本的结构如下：

复制代码

.gradle/
 └── wrapper/
     └── dists/
         └── gradle-6.7.1-all/
             └── <随机ID>/
                 └── gradle-6.7.1-all.zip

2️⃣ 找到或创建版本目录

若该版本目录不存在，可手动创建：

bash 复制代码

mkdir -p ~/.gradle/wrapper/dists/gradle-6.7.1-all/manual

3️⃣ 拷贝 zip 文件

bash 复制代码

mv ~/Downloads/gradle-6.7.1-all.zip ~/.gradle/wrapper/dists/gradle-6.7.1-all/manual/

4️⃣ 配置项目使用本地包

编辑项目文件：

复制代码

gradle/wrapper/gradle-wrapper.properties

两种方式可选：

✅ 方式一：使用官方 URL（Gradle 自动识别本地缓存）

properties 复制代码

distributionUrl=https\://services.gradle.org/distributions/gradle-6.7.1-all.zip

✅ 方式二：强制使用本地路径（完全离线）

properties 复制代码

distributionUrl=file:/Users/<用户名>/.gradle/wrapper/dists/gradle-6.7.1-all/manual/gradle-6.7.1-all.zip

5️⃣ 在 Android Studio 中启用离线模式

菜单路径：

File → Settings → Build, Execution, Deployment → Gradle

勾选：

复制代码

☑ Offline work

6️⃣ 验证是否成功

在项目根目录执行：

bash 复制代码

./gradlew -v

若输出中包含：

复制代码

Gradle 6.7.1
Gradle home: /Users/<用户名>/.gradle/wrapper/dists/gradle-6.7.1-all/...

说明已成功使用本地包构建。

四、优缺点分析

项目	优点	缺点
本地使用 Gradle	✅ 构建速度快 ✅ 不依赖外网 ✅ 版本一致性强 ✅ CI/CD 可离线构建	⚠️ 需要手动管理版本文件 ⚠️ 更新需重新下载 ZIP
在线下载 Gradle	✅ 自动更新 ✅ 无需手动维护	⚠️ 首次构建慢 ⚠️ 依赖网络 ⚠️ 不适合离线环境

五、适用场景总结

场景	推荐方式
公司内网 / 离线开发	✅ 手动下载并使用本地 Gradle 包
普通个人开发环境	✅ 默认在线下载
持续集成环境（CI）	✅ 本地缓存 Gradle 包或挂载共享缓存目录
多项目共享同一版本	✅ 手动放置 ZIP 到统一 `.gradle` 目录中

六、实用命令汇总（macOS）

操作	命令
打开 Gradle 缓存目录	`open ~/.gradle/wrapper/dists`
创建 6.7.1 版本目录	`mkdir -p ~/.gradle/wrapper/dists/gradle-6.7.1-all/manual`
移动 zip 文件	`mv ~/Downloads/gradle-6.7.1-all.zip ~/.gradle/wrapper/dists/gradle-6.7.1-all/manual/`
验证版本使用情况	`./gradlew -v`

✅ 总结

📦 结论一句话：

将 gradle-x.x.x-all.zip 放入
~/.gradle/wrapper/dists/gradle-x.x.x-all/<任意文件夹>/

并在 gradle-wrapper.properties 中指向该版本，即可实现离线构建。

这种方式适合：

网络不稳定或受限；
构建频繁的 Android 项目；
需要保证构建一致性或可重复性；
CI/CD 自动化环境。