GRADLE_USER_HOME 是 Gradle 全局缓存根目录，必须设置以避免 C 盘爆满和多用户冲突；默认路径易引发权限、空格、中文及 Wrapper 冲突问题，推荐通过环境变量统一配置并安全迁移缓存。
GRADLE_USER_HOME 是什么，为什么必须设
GRADLE_USER_HOME 指向 Gradle 的全局缓存根目录，它不是可选配置——只要项目用到依赖下载、Wrapper 解压、构建缓存或插件元数据，Gradle 就会往这里写文件。默认路径是 $HOME/.gradle（macOS/Linux）或 C:Users\.gradle（Windows），但这个位置常导致两个问题：C 盘爆满、多用户/多环境冲突。不显式设置，就等于把缓存和构建状态全交给系统默认路径托管，后续迁移或清理都会被动。
三种设置方式的区别和适用场景
命令行临时设置只影响单次执行，适合调试；环境变量全局生效，覆盖所有终端和 IDE 启动的 Gradle 进程；build.gradle 里硬编码则仅对当前项目有效，且可能被 Wrapper 忽略——因为 Wrapper 在启动 Gradle JVM 前就已读取 GRADLE_USER_HOME，此时项目脚本还没加载。
- 命令行：
gradle -g /path/to/my-gradle-home build，适合验证路径是否可写、测试新仓库位置 - 环境变量（推荐）：
export GRADLE_USER_HOME=/data/gradle-cache（macOS/Linux）或在 Windows 系统属性 → 环境变量中新增变量名GRADLE_USER_HOME，值为D:gradle-cache - build.gradle 中设置：
allprojects { gradle.userHome = file("/path/to/home") }，仅对非 Wrapper 场景可靠；Android Studio 中若启用「Use Gradle from wrapper」，该配置基本无效
常见错误：路径不可写或与 Wrapper 冲突
最典型的报错是 Could not create service of type FileTreeRepository 或构建时卡在 Resolving dependencies，本质是 Gradle 尝试在目标路径下创建 caches/、wrapper/dists/ 时被拒绝。检查点有三个：
- 路径存在且父目录有写权限（Linux/macOS 执行
ls -ld /path/to/home；Windows 右键属性 → 安全） - 路径不能包含空格或中文（尤其 Windows 下
C:My Gradle Home会导致zipStoreBase解析失败） - 如果同时配置了
gradle-wrapper.properties中的distributionBase，它优先级高于GRADLE_USER_HOME环境变量——此时应统一设为GRADLE_USER_HOME，避免两者指向不同位置导致 dists 下载两次
迁移已有缓存时的注意事项
直接移动 .gradle 文件夹后只改环境变量，大概率会触发重复下载或校验失败。真正安全的迁移流程是：
- 先停掉所有正在运行的 Gradle 进程（
pkill -f gradle或任务管理器结束 java.exe） - 复制整个原
.gradle目录（含caches/、wrapper/、daemon/）到新路径 - 设置
GRADLE_USER_HOME并重启终端或 IDE - 首次运行
gradle --stop && gradle build，让 Daemon 重建连接，避免复用旧缓存句柄
别忽略 daemon 目录——它存着 JVM 进程锁和 socket 文件，跨路径残留会导致构建卡死或端口占用错误。
