【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️⃣ 找到或创建版本目录
若该版本目录不存在，可手动创建：
mkdir -p ~/.gradle/wrapper/dists/gradle-6.7.1-all/manual
3️⃣ 拷贝 zip 文件
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 自动识别本地缓存）
distributionUrl=https\://services.gradle.org/distributions/gradle-6.7.1-all.zip
✅ 方式二：强制使用本地路径（完全离线）
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️⃣ 验证是否成功
在项目根目录执行：
./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 自动化环境。