1. 项目概述：为什么你需要关注GRADLE_USER_HOME？

如果你是一名Android开发者，或者正在使用Gradle构建Java、Kotlin项目，那么你一定对Gradle的依赖下载速度慢、本地缓存占用C盘空间、多项目环境依赖混乱这些问题深有感触。每次新开一个项目，或者换一台电脑，漫长的“Downloading https://repo.maven.apache.org/maven2/...”等待过程，足以让你泡杯咖啡回来。更头疼的是，默认情况下，Gradle会把所有下载的依赖包、插件、Wrapper分发文件都堆在用户目录下的.gradle文件夹里（比如Windows的C:\Users\你的用户名\.gradle），日积月累，这个文件夹轻松就能涨到十几个GB，让你的系统盘不堪重负。

GRADLE_USER_HOME环境变量，就是解决这些痛点的“金钥匙”。它不是一个复杂的黑科技，而是一个简单却极其有效的配置项。简单来说，它允许你告诉Gradle：“嘿，别再把缓存文件往我C盘塞了，放到我指定的那个位置去。” 这个指定的位置，可以是你空间充裕的D盘、E盘，甚至可以是一个网络驱动器或者一个全团队共享的目录。理解并正确使用它，不仅能解放你的系统盘，还能在多项目、多环境、团队协作中带来显著的效率提升和一致性保障。对于个人开发者，这是优化开发环境的必备技巧；对于团队，这是统一构建环境、提升CI/CD稳定性的基础配置。

2. GRADLE_USER_HOME核心原理与价值解析

2.1 GRADLE_USER_HOME到底是什么？

从技术定义上讲，GRADLE_USER_HOME是一个环境变量，它指定了Gradle用户主目录（Gradle User Home Directory）的路径。这个目录是Gradle在用户级别存储其缓存和配置信息的“大本营”。你可以把它类比为Maven的本地仓库目录（默认是~/.m2/repository），但它的职责范围更广。

默认情况下，如果你不设置这个环境变量，Gradle会按照以下规则自动确定其位置：

• Unix/Linux/macOS:~/.gradle（即用户家目录下的隐藏文件夹）
• Windows:C:\Users\<用户名>\.gradle

一旦你设置了GRADLE_USER_HOME，Gradle就会完全忽略上述默认路径，将所有用户级别的数据存储在你指定的新位置。

2.2 这个目录里究竟藏了些什么？

理解GRADLE_USER_HOME的价值，需要先看看它里面到底存放了什么“家当”。主要包含以下几大类：

1. 依赖缓存（Dependency Cache）：这是占用空间最大的部分，通常位于caches/modules-2/files-2.1目录下。所有从远程仓库（如Maven Central, Google, JCenter）下载的jar、aar、pom等文件都会被缓存到这里。同一个依赖的相同版本，无论被多少个项目引用，在本地只会存储一份。这是提升构建速度的关键。
2. Wrapper分发文件（Wrapper Distributions）：当你使用gradlew（Gradle Wrapper）时，它会根据gradle/wrapper/gradle-wrapper.properties文件中指定的版本，去下载对应的Gradle发行版（一个ZIP包）。这些ZIP包就下载并解压在wrapper/dists目录下。不同项目、不同版本的Gradle发行版都会存放在这里。
3. 构建缓存（Build Cache，可选）：如果启用了Gradle的构建缓存功能（一种更高级的缓存，可以缓存任务输出），其本地缓存数据默认也存放在这里（caches/build-cache-1）。这可以极大加速增量构建和干净构建。
4. 守护进程（Daemon）日志和文件：Gradle守护进程的日志、运行时的临时文件等。
5. 全局初始化脚本（Init Scripts）：放在init.d目录下的.gradle或.gradle.kts文件，会在任何Gradle构建开始前执行，用于配置全局的仓库、属性、任务等。
6. 全局Gradle属性文件：gradle.properties文件可以放在这里，用于设置所有项目的全局属性，如JVM参数（org.gradle.jvmargs）、是否启用并行构建等。

注意：GRADLE_USER_HOME存放的是用户级别的全局数据，它与项目级别的.gradle目录（位于项目根目录下）是分开的。项目级别的.gradle主要存放该项目的构建缓存、任务历史等临时数据，通常体积较小，且可以随时删除（下次构建会重新生成）。

2.3 为什么要自定义GRADLE_USER_HOME？四大核心价值

1. 释放系统盘空间（最直接的价值）：将缓存目录从默认的C盘迁移到空间更大的其他磁盘分区，立竿见影地解决C盘空间告急的问题。这对于使用SSD作为系统盘（容量通常较小）的开发者尤其重要。
2. 提升构建速度（尤其是多项目环境）：当你同时开发多个项目，或者团队内多个项目共享技术栈时，它们会依赖大量相同的第三方库。如果所有项目都指向同一个GRADLE_USER_HOME，那么任何一个项目下载过的依赖，其他项目都可以直接使用缓存，无需重复下载。在CI/CD服务器上，可以预先准备一个“暖”过的缓存目录，让每次构建都飞快。
3. 统一团队与CI环境，确保一致性：在团队开发中，可以通过统一配置（如将GRADLE_USER_HOME指向一个网络共享路径或由基础设施团队维护的标准路径），确保所有开发者和CI服务器使用完全相同的依赖缓存。这能避免因网络问题或仓库镜像不同导致的依赖版本细微差异，实现“构建即产物”的可靠性。
4. 便于缓存清理与管理：缓存目录集中在一个你指定的、容易找到的位置，方便你定期清理过时或无用的缓存（例如，删除wrapper/dists中不再使用的旧版本Gradle，或清理caches中很久未访问的依赖），而不必在系统盘的用户目录里小心翼翼地操作。

3. 如何设置GRADLE_USER_HOME：四种方法详解

设置GRADLE_USER_HOME有多种方式，优先级从高到低依次为：命令行参数 > 环境变量 > 项目属性 > 默认路径。我们将详细拆解每种方法的操作步骤、适用场景及注意事项。

3.1 方法一：通过系统环境变量设置（推荐用于个人开发环境）

这是最常用、影响范围最广的设置方式。设置后，在该用户会话下运行的所有Gradle构建（无论是命令行还是IDE）都会生效。

Windows系统设置步骤：

1. 在桌面或文件资源管理器中，右键点击“此电脑”或“计算机”，选择“属性”。
2. 点击“高级系统设置”。
3. 在弹出的“系统属性”窗口中，点击“环境变量”按钮。
4. 在“用户变量”或“系统变量”区域（建议用用户变量，仅影响当前账户），点击“新建”。
5. 变量名输入：GRADLE_USER_HOME
6. 变量值输入：你希望设置的路径，例如D:\Development\GradleCache或E:\gradle-user-home。

   实操心得：路径中尽量不要包含中文和空格，虽然Gradle可能支持，但某些底层工具或脚本在处理时可能会出错。使用全英文路径是最稳妥的选择。

7. 点击“确定”保存所有打开的窗口。
8. 关键一步：你需要关闭并重新打开所有命令行终端（CMD, PowerShell）和IDE（Android Studio, IntelliJ IDEA），新的环境变量才会被这些程序读取。

macOS / Linux系统设置步骤：通常通过修改shell的配置文件来实现，如~/.bashrc,~/.zshrc,~/.bash_profile。

1. 打开终端。
2. 使用文本编辑器打开你的shell配置文件，例如对于zsh：

   nano ~/.zshrc

3. 在文件末尾添加一行：

   export GRADLE_USER_HOME=/path/to/your/gradle/home

   例如：export GRADLE_USER_HOME=$HOME/Development/GradleCache（$HOME代表你的用户家目录）。
4. 保存并退出编辑器（在nano中按Ctrl+X，然后按Y确认，再按回车）。
5. 让配置立即生效：

   source ~/.zshrc

6. 验证是否设置成功：

   echo $GRADLE_USER_HOME

   应该输出你设置的路径。

注意事项：通过环境变量设置是“一劳永逸”的，但它的影响是全局的。如果你需要在某些特定场景下使用不同的缓存目录（比如一个项目想用独立的缓存做测试），这种方法就不够灵活。

3.2 方法二：通过命令行参数设置（灵活用于单次构建）

在运行gradle或gradlew命令时，可以通过-g或--gradle-user-home参数临时指定本次构建使用的用户主目录。

命令格式：

# 使用 gradlew (Wrapper) ./gradlew -g /custom/path/to/gradle/home build # 或使用完整的参数名 ./gradlew --gradle-user-home=/custom/path/to/gradle/home build # 使用全局安装的 gradle 命令同理 gradle -g /custom/path/to/gradle/home build

适用场景：

• 快速测试：你想测试一个新的、干净的缓存目录对构建是否有影响，又不想改动全局配置。
• 隔离构建：某个项目的依赖非常特殊或可能存在冲突，你想为它创建一个完全独立的缓存环境。
• CI/CD脚本：在CI流水线中，你可能希望将缓存目录挂载到一个Docker Volume或特定的工作空间路径，便于在构建步骤间持久化缓存，这时在构建命令中指定就非常方便。

提示：命令行参数的优先级最高，它会覆盖环境变量和项目属性的设置。

3.3 方法三：通过项目中的gradle.properties文件设置（项目级配置）

你可以在项目的gradle.properties文件中设置gradle.user.home属性。这个文件可以放在两个位置：

• 项目根目录：仅对该项目生效。
• GRADLE_USER_HOME目录：对所有项目生效（如果已通过方法一或二设置了该目录）。

操作步骤：

1. 在项目根目录下，找到或创建gradle.properties文件。
2. 在文件中添加一行：

   gradle.user.home=/some/custom/path

3. 保存文件。

特点与局限：

• 优先级：它的优先级低于命令行参数，但高于系统默认路径。如果同时设置了环境变量和项目属性，项目属性会生效（因为Gradle在读取项目配置时，会覆盖环境变量的值？这里需要纠正：实际上，通过gradle.properties设置的gradle.user.home属性，其优先级是低于环境变量GRADLE_USER_HOME的。Gradle官方文档明确指出，环境变量的优先级高于项目属性文件。这是一个常见的理解误区，务必注意）。
• 影响范围：放在项目根目录时，只影响当前项目。这似乎很理想，但存在一个“先有鸡还是先有蛋”的问题：Gradle需要读取gradle.properties才能知道缓存目录在哪，但在读取这个文件之前，它可能已经基于环境变量或默认路径进行了一些初始化操作。因此，这种方式并不总是可靠，尤其是在涉及Wrapper分发文件下载时。不推荐作为主要的配置方式，更适合作为环境变量配置的补充或文档说明。

3.4 方法四：在IDE中配置（针对IDE发起的构建）

如果你主要使用Android Studio或IntelliJ IDEA进行开发，也需要在IDE中配置，以确保IDE内置的Gradle执行器也能使用正确的缓存路径。

Android Studio / IntelliJ IDEA 配置步骤：

1. 打开File->Settings(Windows/Linux) 或IntelliJ IDEA->Preferences(macOS)。
2. 导航到Build, Execution, Deployment->Build Tools->Gradle。
3. 在右侧面板中，找到Gradle user home的输入框。
4. 默认情况下，它可能显示为“Default (.gradlein the user's home directory)”。你需要点击输入框旁边的文件夹图标，或者直接输入你通过环境变量设置的路径（例如D:\Development\GradleCache）。
5. 点击“OK”或“Apply”保存。

为什么这步很重要？IDE在运行Gradle任务（如Sync、Build、Run）时，并不总是继承你系统终端的环境变量。特别是在Windows上，IDE可能是在一个独立的环境中启动的。因此，即使你在系统环境变量中设置了GRADLE_USER_HOME，IDE也可能读不到，导致缓存仍然写入默认的C盘目录。在这里显式配置一次，可以确保万无一失。

4. 迁移现有缓存与目录结构解析

当你第一次设置好新的GRADLE_USER_HOME路径后，这个目录是空的。如果你不想重新下载所有依赖（那将非常耗时），可以将旧缓存目录下的内容迁移过来。

4.1 安全迁移操作指南

1. 完全关闭Gradle相关进程：确保所有IDE、命令行终端都已关闭，没有Gradle守护进程在运行。在Windows任务管理器或macOS/Linux的ps命令中检查是否有gradle或java进程。
2. 复制而非剪切：建议先使用复制（Copy）操作，将原.gradle目录（默认在C:\Users\你的用户名\.gradle或~/.gradle）下的所有内容，复制到新的GRADLE_USER_HOME目录下。
3. 验证构建：打开一个新的终端或IDE，在新路径下运行一次gradle build或./gradlew build，确保构建成功，并且新的缓存目录开始被写入数据。
4. 备份与删除：确认一切正常后，你可以将旧的.gradle目录重命名（例如改为.gradle_backup）作为备份。观察一段时间（比如一两周）后，如果没有任何问题，再将其删除以释放C盘空间。

警告：千万不要在Gradle进程运行时直接移动或删除缓存目录，这可能导致构建失败甚至损坏缓存数据。

4.2 新目录结构详解与清理策略

迁移后，你的新GRADLE_USER_HOME目录结构大致如下，了解它们有助于日常管理和清理：

你的GRADLE_USER_HOME路径/ ├── caches/ # 缓存目录，占用空间最大 │ ├── modules-2/ # 依赖缓存主目录 │ │ └── files-2.1/ # 实际依赖jar/aar文件存储地，按groupId/artifactId/version哈希存储 │ ├── build-cache-1/ # 构建缓存（如果启用） │ └── ... (其他缓存，如jars-3, transforms-2等) ├── wrapper/ # Wrapper分发文件 │ └── dists/ # 不同版本的Gradle发行版ZIP和解压目录 │ ├── gradle-8.5-bin/ │ ├── gradle-8.6-bin/ │ └── ... ├── daemon/ # 守护进程相关文件 ├── init.d/ # 全局初始化脚本 ├── gradle.properties # 全局Gradle属性文件 └── ...

定期清理建议：

• wrapper/dists：这里存放着所有下载过的Gradle发行版。如果你确定团队或项目已经统一升级到新版本（如8.6），旧的版本（如8.3, 8.4）可以安全删除。直接删除对应的版本文件夹即可。
• caches/modules-2/files-2.1：这里的文件由Gradle自动管理，通常不需要手动删除。Gradle有缓存清理机制（如--refresh-dependencies参数会刷新动态版本）。如果你急需空间，可以删除整个caches目录，Gradle会在下次构建时重新下载所需依赖。
• daemon：守护进程日志可以清理，但通常体积不大。
• 最安全的清理命令：在项目根目录下运行./gradlew --stop停止所有守护进程，然后运行./gradlew clean清理项目输出，最后可以手动删除caches中你认为不必要的部分。对于构建缓存，Gradle提供了./gradlew buildCacheClean命令来清理。

5. 高级应用与团队协作场景

5.1 在CI/CD流水线中优化构建缓存

在Jenkins、GitLab CI、GitHub Actions等持续集成环境中，合理利用GRADLE_USER_HOME可以大幅缩短构建时间。核心思路是：将缓存目录作为构建产物（Artifact）或缓存（Cache）在流水线运行间持久化。

以GitHub Actions为例的配置思路：

jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Gradle uses: gradle/actions/setup-gradle@v3 with: # 这个action会自动配置GRADLE_USER_HOME到一个可缓存的位置 cache-read-only: ${{ github.ref != 'refs/heads/main' }} # 仅主分支推送时写入缓存 # 或者你也可以手动指定 # gradle-home: ${{ runner.temp }}/.gradle - name: Build with Gradle run: ./gradlew build # actions/setup-gradle 会自动处理缓存的保存和恢复

关键点在于利用CI平台提供的缓存机制（如GitHub Actions的actions/cache），将GRADLE_USER_HOME目录缓存起来。这样，下一次流水线运行时，就能直接复用之前下载的依赖和Wrapper，实现“暖缓存”构建。

团队CI服务器共享缓存：在自建的Jenkins服务器上，可以将GRADLE_USER_HOME指向一个所有构建节点（Agent）都能访问的网络共享存储（如NFS目录）。这样，任何一个节点下载的依赖，其他节点都可以直接使用，避免了每个节点单独下载的带宽和时间浪费。需要注意网络延迟和文件锁问题。

5.2 多版本Gradle与项目隔离策略

有时你需要同时维护使用不同Gradle版本的项目（例如，一个老项目用Gradle 6.x，新项目用8.x）。虽然wrapper/dists可以存放多个版本，但全局的init.d脚本和属性可能会产生冲突。

策略：为不同版本簇设置不同的GRADLE_USER_HOME你可以准备多个缓存目录，并通过脚本或别名快速切换。

# 在.bashrc或.zshrc中设置别名 alias gradle6='GRADLE_USER_HOME=~/.gradle6 ./gradlew' alias gradle8='GRADLE_USER_HOME=~/.gradle8 ./gradlew' # 使用时 cd /path/to/old-project gradle6 build cd /path/to/new-project gradle8 build

这样，Gradle 6.x和8.x项目的缓存、配置完全隔离，互不影响。

5.3 与构建缓存（Build Cache）的配合

Gradle的构建缓存（Build Cache）是一个更高级的特性，它可以缓存任务输出（如编译后的class文件、测试结果等），而不仅仅是依赖。它的本地缓存目录默认也在GRADLE_USER_HOME下（caches/build-cache-1）。

配置建议：在GRADLE_USER_HOME/gradle.properties中启用和配置构建缓存：

# 启用构建缓存 org.gradle.caching=true # 设置本地缓存大小（默认5GB） org.gradle.cache.local.directory.size=10G # 也可以指定一个完全不同的路径（如果需要） # org.gradle.cache.local.directory=/another/path/build-cache

将GRADLE_USER_HOME设置到一个高速磁盘（如NVMe SSD）上，可以进一步提升构建缓存的读写效率。

6. 常见问题排查与实战技巧

6.1 问题排查清单

6.2 实战技巧与心得

1. 路径选择有讲究：最好将GRADLE_USER_HOME设在一个固态硬盘（SSD）上。依赖解压、缓存读写都是大量小文件操作，SSD的随机读写性能远胜于机械硬盘，能明显提升构建速度。
2. 版本控制系统的忽略配置：绝对不要将GRADLE_USER_HOME目录或任何项目的.gradle目录提交到Git等版本控制系统！确保你的.gitignore文件包含.gradle/和gradle-user-home/（如果你自定义了名称）。
3. 环境变量验证命令：在终端中，快速验证GRADLE_USER_HOME是否生效的一个好方法是运行一个简单的Gradle任务并观察输出路径：

   ./gradlew --dry-run tasks 2>&1 | head -20

   在输出的开头部分，Gradle通常会打印出“Using gradle home at: /your/custom/path”之类的信息。
4. 组合使用策略：我个人最推荐的策略是：为个人电脑设置全局的GRADLE_USER_HOME环境变量到SSD的非系统盘，同时在每个项目的README或构建脚本中，通过gradle.properties示例文件说明推荐的本地配置，并在CI/CD流水线中显式配置缓存路径和缓存恢复策略。这样兼顾了个人开发的便利性、项目文档的完整性和自动化流程的效率。
5. 清理脚本：可以编写一个简单的Shell脚本或批处理文件，用于定期清理过期的Gradle Wrapper分发版本，例如只保留最近使用的3个版本。这能帮你自动管理磁盘空间。