Gradle 与 Android 构建缓存机制全面总结

最新推荐文章于 2026-06-13 07:08:21 发布

原创最新推荐文章于 2026-06-13 07:08:21 发布 · 750 阅读 ·

大模型引用 1 次

本内容遵循CC 4.0 BY-SA版权协议

关注

标签

#android #缓存

分类开发工具

本总结涵盖项目复制行为、全局依赖缓存管理、SDK 管理等核心开发环境配置，帮助你彻底理解并优化构建流程。

当你复制一个 Android 项目时，可能会观察到 Gradle 同步过程中出现“下载”行为。这并非总是真正的“重新下载”，其原因如下：

下载类型	是否真正下载	原因说明
重新下载 Gradle 发行版 (`gradle-X.X-all.zip`)	✅ 是	复制的项目中 `gradle-wrapper.properties` 指定了 Gradle 版本。如果本地 `wrapper/dists/` 目录没有该版本，Gradle Wrapper 会从网络下载。但如果其他项目已下载过同一版本，则不会重复下载（共享缓存）。
重新下载第三方依赖库 (如 Retrofit, Glide)	❌ 通常不是	这些依赖存储在全局缓存 `~/.gradle/caches/modules-2/` 中。只要版本号完全一致，Gradle 会直接复用已有文件，不会重新下载。你看到的“下载”进度条通常是 Gradle 在解析依赖图和建立链接，而非网络传输。
首次同步新项目	✅ 是	如果这是你第一次使用某个 Gradle 版本或依赖库，且缓存中不存在，则必须从网络下载。

📌 关键结论：复制项目后，“重新下载”的主要是 Gradle 工具本身（如果未缓存），而项目依赖库几乎总是被复用，避免了真正的重复下载。

路径：
- Windows: C:\Users\<用户名>\.gradle\
- macOS: /Users/<用户名>/.gradle/
- Linux: /home/<用户名>/.gradle/
内容：
- caches/: 存放所有项目依赖库（modules-2/）和构建缓存。
- wrapper/dists/: 存放不同版本的 Gradle 发行包。

方法	详细说明	优先级	推荐度
环境变量 `GRADLE_USER_HOME`	1. 创建目标目录（如 `D:\Android\.gradle`）。 2. 设置系统环境变量： • 变量名：`GRADLE_USER_HOME` • 变量值：`D:\Android\.gradle` 3. 重启 Android Studio。	高	⭐⭐⭐⭐⭐ 最推荐。全局生效，稳定可靠。
IDE (Android Studio) 设置	1. 打开 Android Studio。 2. `File` → `Settings` → `Build, Execution, Deployment` → `Gradle`。 3. 在 “Gradle user home” 输入框填写新路径（如 `D:\Android\.gradle`）。	中	⭐⭐⭐⭐ 直观易用，但仅对当前 IDE 生效。
`gradle.properties` 文件	在项目根目录或全局 `~/.gradle/gradle.properties` 中添加： `gradleUserHome=D:/Android/.gradle` ⚠️ 注意：此方法优先级最低，会被环境变量和 IDE 设置覆盖。	低	⭐⭐

设置 GRADLE_USER_HOME：将缓存迁移到空间充足的磁盘，从根本上解决问题。
手动复制已有缓存：
1. 关闭 Android Studio。
2. 将旧的 .gradle 文件夹整体复制到新位置（如 D:\Android\.gradle）。
3. 通过上述任一方法将 GRADLE_USER_HOME 指向新位置。
4. 重启 Android Studio，即可零下载使用所有已有依赖和 Gradle 版本。
利用缓存共享机制： Gradle 的设计保证了相同版本的依赖和 Gradle 包在所有项目间自动共享，无需任何操作。

路径：
- Windows: C:\Users\<用户名>\AppData\Local\Android\Sdk
- macOS: /Users/<用户名>/Library/Android/sdk
- Linux: /home/<用户名>/Android/Sdk

项目级指定 (local.properties)：
```
sdk.dir=C\:\\Android\\Sdk
```
此文件通常由 Android Studio 自动生成，不建议手动修改。
IDE 全局指定：
- Android Studio → Settings → Appearance & Behavior → System Settings → Android SDK。
- 在 “Android SDK Location” 中可查看和更改路径。

备份原 SDK：关闭 Android Studio，备份整个 Android/Sdk 目录。
移动到新位置：将 Sdk 文件夹复制到目标磁盘（如 D:\Android\Sdk）。
更新路径：
- 方法一（推荐）：在 Android Studio 的 SDK 设置中，将路径改为 D:\Android\Sdk。AS 会自动更新所有项目的 local.properties。
- 方法二：手动编辑每个项目的 local.properties 文件，修改 sdk.dir。
验证：打开项目，确保能正常编译和运行。

✅ 机制说明： SDK 本身就是一个“巨型缓存”，包含了所有下载的平台、工具、系统镜像等。迁移就是复制，复制即避免重复下载。只要文件完整，Gradle 和 AS 能立即识别并使用。

Gradle 缓存迁移：使用 GRADLE_USER_HOME 环境变量 将 .gradle 目录迁移到大容量磁盘。
SDK 迁移：通过 Android Studio 设置将 Android/Sdk 移动到非系统盘。
善用复制：利用 Gradle 和 SDK 的本地缓存与共享机制，通过手动复制文件夹的方式，实现“一次下载，永久复用”，彻底告别重复下载的烦恼。

遵循以上策略，你的开发环境将变得高效、整洁且可持续。