GRADLE_HOME指向Gradle可执行程序路径，仅影响手动运行gradle命令；GRADLE_USER_HOME指向全局状态存储目录，默认为用户目录下.gradle，存放缓存、wrapper下载版本、守护进程等，决定构建速度与稳定性，IDE和gradlew均依赖它。

GRADLE_HOME 和 GRADLE_USER_HOME 是两个完全不同的概念

很多人一上来就改错环境变量，结果 gradle -v 能跑通，但项目构建还是卡在下载、缓存失效、甚至 IDE 报 “No Gradle distribution found”。根本原因是混淆了这两个目录的职责。

GRADLE_HOME 指向的是可执行二进制文件位置

它只影响你手动运行 gradle 命令时用的是哪一套 Gradle 程序。比如你解压 gradle-8.10-bin.zip 到 D:\gradle\8.10，那 GRADLE_HOME 就该设为这个路径，%GRADLE_HOME%\bin 加进 PATH 后，终端里敲 gradle 才能调起它。

• 不设置 GRADLE_HOME 也能用 —— 只要没手动调命令行，Android Studio 或 gradlew 都不依赖它
• 设置了但路径错了，gradle -v 会报 'gradle' is not recognized
• GRADLE_HOME 不管缓存、不存依赖、不影响 wrapper 下载行为

GRADLE_USER_HOME 指向的是全局状态存储位置

这才是真正决定构建速度和稳定性的关键路径。默认是 C:\Users\<username>\.gradle</username>，里面存着：

• caches/：所有项目的依赖 jar、插件、脚本编译结果（复用率最高）
• wrapper/dists/：gradlew 自动下载的 Gradle 发行版（比如 gradle-8.7-bin.zip 解压后的内容）
• daemon/：后台构建守护进程的 socket 和日志
• jdks/（较新版本）：通过 gradle java-toolchains 自动管理的 JDK 缓存

如果你 C 盘快满了，或者想让多用户/多项目共享缓存，必须改这里 —— 设置环境变量 GRADLE_USER_HOME=D:\gradle_user_home，然后把原 .gradle 里的 caches、wrapper、daemon 复制过去（不用复制 notifications 或临时锁文件 .lock）。

Gradle 9.8.0

下载

IDE 和 gradlew 对这两个变量的使用逻辑完全不同

Android Studio / IntelliJ 默认忽略 GRADLE_HOME，它只认你项目设置里选的 Gradle 版本（可以是 wrapper、本地路径、或自动下载）。但它会读 GRADLE_USER_HOME 来决定往哪儿写缓存 —— 所以改完变量后，必须重启 IDE，否则它还在往旧路径写。

• gradlew（项目根目录下的包装脚本）完全不看 GRADLE_HOME，它只根据 gradle/wrapper/gradle-wrapper.properties 里的 distributionUrl 去 GRADLE_USER_HOME/wrapper/dists 找或下对应版本
• 如果同时设置了 GRADLE_USER_HOME 和 -g 参数（如 gradle build -g E:\temp），后者优先级更高，但仅对当次命令生效
• Windows 上用系统环境变量设置最稳妥；Linux/macOS 推荐在 ~/.bashrc 或 ~/.zshrc 里 export GRADLE_USER_HOME=/path

最容易被忽略的一点：改完 GRADLE_USER_HOME 后第一次运行 gradlew，它会重新下载整个 dist 并解压，耗时可能超过 5 分钟 —— 不是失败，是进度条没显示而已。