Android Gradle 缓存与目录结构解析
在 Android 开发中，合理管理构建缓存和文件目录不仅能加快编译速度，还能有效避免磁盘空间被无形吞噬。Android 的目录结构主要分为两大类：项目级目录（随项目删除而销毁） 和 用户全局目录（独立存在，跨项目共享）。
一、 项目级目录（随项目文件夹删除而销毁）
此类目录位于项目根目录下，仅对当前项目生效。
1. .gradle/ 文件夹（项目级构建缓存与中间产物）
- 路径 ：
项目根目录/.gradle/ - 主要内容 ：
- 任务状态缓存 （
caches/）：保存上一次编译的任务（Tasks）输入与输出快照，用于增量编译。 - 配置缓存 （
configuration-cache/）：存储配置阶段（Configuration Phase）的计算结果，减少后续编译的配置耗时。 - 依赖解析快照：记录当前项目依赖解析生成的缓存。
- 临时文件：Transform API 在处理字节码时生成的临时中转文件。
- 任务状态缓存 （
- 特点：专属于当前项目。如果编译出现逻辑混乱或缓存失效，可以安全删除此文件夹，Gradle 会在下次编译时自动重建。
2. build/ 文件夹（模块编译输出产物）
- 路径 ：
- 项目根目录：
项目根目录/build/ - 各模块目录：
项目根目录/app/build/、项目根目录/模块名/build/
- 项目根目录：
- 主要内容 ：
- 编译产物：Class 文件、DEX 文件、AAR/JAR 包、最终生成的 APK/Bundle 文件。
- 中间产物：合并后的 AndroidManifest.xml、资源编译产物（flat 格式）、混淆映射表（mapping.txt）、BuildConfig.java。
- 辅助信息：Lint 检查报告、单元测试及 Instrumented 测试结果、编译日志。
- 清理方式 ：执行
./gradlew clean任务会清空项目中所有模块的build/文件夹。
3. gradle/wrapper/ 文件夹（Gradle Wrapper 声明）
- 路径 ：
项目根目录/gradle/wrapper/ - 主要文件 ：
gradle-wrapper.properties：定义了项目所需的 Gradle 版本（如distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-all.zip）。gradle-wrapper.jar：负责下载并引导执行特定版本 Gradle 的核心代码。
- 注意 ：此处不包含 Gradle 的运行时程序本身（即不含几十MB的发行包），仅作为版本声明文件。
4. 基础配置文件
- 文件 ：
local.properties、gradle.properties、settings.gradle、build.gradle（或其 Kotlin DSL 对应的.kts文件）。 - 作用：定义项目独有的 SDK 路径、JVM 参数、模块依赖关系及构建逻辑。
5. .idea/ 文件夹（IDE 索引与配置）
- 路径 ：
项目根目录/.idea/ - 作用：存储 Android Studio (IntelliJ IDEA) 针对当前项目生成的代码索引、运行/调试配置、代码风格设置等。
二、 用户全局目录（独立存在，不随项目删除而销毁）
此类目录通常位于用户主目录下（除非手动更改了环境变量），为所有本地 Gradle 项目所共享。
1. Gradle 全局配置与缓存目录（GRADLE_USER_HOME）
默认路径：
- Windows ：
C:\Users\<用户名>\.gradle\ - macOS / Linux ：
~/.gradle/
该目录下包含以下核心子目录：
① Gradle 发行包本体（wrapper/dists/）
- 路径 ：
~/.gradle/wrapper/dists/ - 原理 ：当首次编译一个声明了新版本 Gradle（例如
7.5-all）的项目时，Gradle Wrapper 会自动将对应的 ZIP 包下载并解压到此目录。 - 复用性：所有声明相同版本的本地项目都会共用此处已解压的 Gradle 运行时，避免重复下载。
② Maven 依赖缓存（caches/modules-2/files-2.1/）
- 路径 ：
~/.gradle/caches/modules-2/files-2.1/ - 作用 ：存放从远程仓库（如 Google Maven、Maven Central、阿里云镜像等）下载的所有第三方库（
.jar、.aar）、POM 配置文件及源码包。 - 复用性：全局共享。一旦某个依赖库被下载，其他项目引用相同版本的库时将直接从这里读取。
③ 转换与插件缓存（caches/transforms-x/、caches/jars-x/）
- 作用 ：
- 存放 AGP (Android Gradle Plugin) 对依赖进行转换（Transform）后的产物，例如将 AAR 解压、Jetifier 对旧支持库的迁移转换等。
- 存储 Gradle 插件及构建脚本编译后的 JAR 缓存。
④ 全局属性配置文件（gradle.properties）
- 路径 ：
~/.gradle/gradle.properties - 作用 ：可在其中配置全局的 JVM 堆大小、代理设置（如
systemProp.http.proxyHost等），配置会应用到本地所有的 Gradle 项目中。
2. Android SDK 目录
路径通常在 local.properties 的 sdk.dir 中指定，默认路径通常为：
- Windows ：
C:\Users\<用户名>\AppData\Local\Android\Sdk - macOS ：
~/Library/Android/sdk - Linux ：
~/Android/Sdk - 主要内容：Build-Tools（编译工具链）、Platforms（系统 API）、Platform-Tools（adb、etc）、Emulator（模拟器）、NDK 及 CMake 等。
3. Android Studio IDE 全局缓存
- Windows ：
C:\Users\<用户名>\AppData\Local\Google\AndroidStudio<版本> - macOS ：
~/Library/Caches/Google/AndroidStudio<版本> - 主要内容：IDE 内部的代码索引缓存、系统配置、模拟器镜像配置及插件。
4. Maven 本地仓库
- 路径 ：
~/.m2/repository/ - 作用 ：如果项目配置了
mavenLocal()，Gradle 在解析依赖时会优先检索此目录。通常用于存放本地自行发布并进行联调的依赖包。
三、 结构对比表
| 目录位置 | 随项目删除而消失？ | 主要作用 | 常见清理方式 |
|---|---|---|---|
项目内 build/ |
是 | 当前模块编译输出（APK、Class 等） | 执行 ./gradlew clean 任务 |
项目内 .gradle/ |
是 | 增量编译状态、配置缓存及任务输出缓存 | 直接手动删除 .gradle/ 文件夹 |
项目内 gradle/wrapper/ |
是 | 声明项目所需的 Gradle 版本及引导程序 | 随项目目录一同手动删除 |
全局 ~/.gradle/wrapper/dists/ |
否 | 存储解压后的 Gradle 发行包本体 | 手动删除不需要的旧版本子目录 |
全局 ~/.gradle/caches/modules-2/ |
否 | 缓存第三方库（JAR/AAR）及源码 | 建议在 IDE 中执行 Invalidate Caches 或手动清理特定依赖 |
| 全局 Android SDK | 否 | 编译、打包、调试 Android 应用所需的核心工具链 | 通过 Android Studio 的 SDK Manager 管理 |
项目内 .idea/ |
是 | Android Studio 针对该项目的索引与运行配置 | 直接手动删除，重新打开项目即可重建 |
四、 常见疑问与维护建议
Q1：为什么删掉项目重新拉取后，首次编译依然很快，且不需要重新下载依赖？
答 ：因为依赖的 JAR/AAR 文件保存在用户全局目录 ~/.gradle/caches/modules-2/ 中。只要全局目录中的依赖未被清理，新项目或重新拉取的项目在编译时，Gradle 会通过校验哈希值直接复用本地缓存。
Q2：./gradlew clean 能解决哪些缓存问题？能清理全局缓存吗？
答：
- 能解决：模块编译输出不一致、过期的 Class 文件、未及时更新的临时资源文件等。
- 不能解决：由于网络中断导致的损坏依赖、不完整的 Gradle 发行包、IDE 代码索引失效。
- 范围 ：它仅能清理项目目录内的
build/文件夹，无法触及~/.gradle下的任何全局缓存。
Q3：什么情况下需要手动清理用户全局目录中的 ~/.gradle/caches？
答：
- 依赖损坏 ：由于网络波动导致下载的依赖文件不完整或损坏，出现
ZipException或类找不到的错误。 - 快照版本（SNAPSHOT）未更新：远程仓库的 SNAPSHOT 版本已更新，但本地由于缓存机制未能及时拉取。
- 磁盘空间严重不足：长期开发累积了多个历史版本的第三方库，占用了几十 GB 的空间。
- 清理方法 ：关闭 Android Studio，定位到
~/.gradle/caches/，直接手动删除modules-2或transforms目录，随后重新导入项目同步。
Q4：在 CI/CD（构建机器）上，如何合理配置这些缓存以优化构建速度？
答 ： 在 CI 流程中，磁盘空间的占用大头通常是 ~/.gradle/caches/modules-2 和 ~/.gradle/wrapper/dists。
- 推荐做法 ：在 Jenkins 或 GitHub Actions 等构建流中，建议将
~/.gradle/caches和~/.gradle/wrapper目录设置为持久化缓存（Cache Target）。这样可以避免每次构建都从网络重新下载依赖，大幅缩短流水线执行时间。