不配置GRADLE_HOME虽可运行gradle -v，但会导致wrapper初始化失败、IDE识别异常、GRADLE_USER_HOME失效三类问题；GRADLE_HOME必须指向解压根目录（不含bin），且变量名须严格为GRADLE_HOME。
不配置 GRADLE_HOME 也能用 Gradle，但会出问题
Gradle 二进制本身不强制依赖 GRADLE_HOME 环境变量——只要 gradle 命令能被系统找到（即 bin 目录在 PATH 中），gradle -v 就能跑通。但跳过 GRADLE_HOME 配置，实际开发中很快会遇到三类典型故障：
-
gradle wrapper初始化失败：某些老版本 Wrapper 脚本（如 Gradle < 6.0）会尝试读取GRADLE_HOME推导默认缓存路径，缺失时可能 fallback 到不可写目录（如/tmp或用户根目录），导致构建中途报Permission denied - IDE（IntelliJ / Android Studio）识别异常：IDE 的 Gradle 设置页常把
GRADLE_HOME当作“已安装 Gradle”的信号。没配它，IDE 可能反复提示“未检测到本地安装”，转而强行下载 wrapper 包，哪怕你本地已有完整gradle-8.6-all.zip - 自定义
GRADLE_USER_HOME时行为错乱：如果你手动设了GRADLE_USER_HOME指向私有仓库（比如和 Maven 共用~/.m2/repository），Gradle 内部某些初始化逻辑仍会回退检查GRADLE_HOME是否存在，缺失时可能忽略你的GRADLE_USER_HOME设置，继续往默认~/.gradle写缓存
GRADLE_HOME 必须指向解压后的根目录，不是 bin 子目录
常见错误是把环境变量值设成 C:\Gradle\gradle-8.6\bin 或 /usr/local/gradle/bin，这会导致 Gradle 启动时找不到 lib/ 下的核心 JAR，直接报错：
ERROR: Could not find or load main class org.gradle.wrapper.GradleWrapperMain
正确做法是：
- Windows：
GRADLE_HOME设为C:\Gradle\gradle-8.6（不含\bin） - macOS / Linux：
GRADLE_HOME设为/usr/local/gradle/gradle-8.6（同样不含/bin） - 然后确保
%GRADLE_HOME%\bin（Win）或$GRADLE_HOME/bin（macOS/Linux）已加入PATH
用 Wrapper 时，GRADLE_HOME 的作用其实变小了
如果你只通过项目根目录的 ./gradlew（Linux/macOS）或 gradlew.bat（Windows）运行构建，Gradle Wrapper 会完全绕过系统级 GRADLE_HOME，而是根据 gradle/wrapper/gradle-wrapper.properties 里的 distributionUrl 自行下载或加载对应版本。此时：
- 配置
GRADLE_HOME对./gradlew build没影响 - 但
gradle build（全局命令）仍依赖它；混用两种方式时，不一致容易引发版本冲突（比如gradle -v显示 8.6，./gradlew -v却是 7.5） - 团队协作中，建议统一用 Wrapper，并在文档里注明
distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-all.zip，比依赖每人配对的GRADLE_HOME更可靠
最容易被忽略的一点：Windows 下变量名大小写敏感吗？
Windows 系统本身不区分环境变量大小写，但 Gradle 的 JVM 启动脚本（gradle.bat）内部用的是 %GRADLE_HOME% 字面量匹配。如果误配成 gradle_home 或 Gradle_Home，脚本读不到值，就会静默 fallback 到默认逻辑——通常表现为构建速度变慢（反复校验缓存）、或某些插件（如 gradle-profiler）无法定位本地安装路径。务必确认变量名拼写完全一致，且在“系统变量”而非“用户变量”中新建（避免权限或作用域问题）。
