Gradle命令不识别、版本冲突、JAVA_HOME未识别、daemon卡顿四大问题需分别排查：PATH未正确包含$GRADLE_HOME/bin或%GRADLE_HOME%\bin；wrapper优先级高于全局Gradle；JAVA_HOME必须指向含javac的JDK 17+；daemon堆内存不足需改org.gradle.jvmargs并执行--stop生效。
Gradle命令不识别：PATH没配对
输 gradle -v 报“command not found”或“不是内部或外部命令”，基本就是 GRADLE_HOME 和 PATH 没生效。
关键不是“配了没”，而是“配对没”——GRADLE_HOME 必须指向解压后的根目录（比如 /opt/gradle/gradle-8.10），而 PATH 必须包含 $GRADLE_HOME/bin（Linux/macOS）或 %GRADLE_HOME%\bin（Windows）。
- Windows 用户常把
GRADLE_HOME设成C:\gradle，但实际解压后是C:\gradle\gradle-8.10，漏掉子目录就找不到gradle.bat - macOS/Linux 用户用
~或$HOME写路径，但 shell 启动文件（如~/.zshrc）里变量展开失败，建议用绝对路径 - 配完别忘了重开终端，或者手动执行
source ~/.zshrc（macOS）或refreshenv（PowerShell）
Gradle版本冲突：wrapper优先级高于全局安装
项目里有 gradlew，运行 ./gradlew build 时，根本不会走你系统装的 gradle 命令，而是用 gradle/wrapper/gradle-wrapper.properties 里指定的版本。
这意味着：你本地装了 8.10，但项目配置的是 7.6，那它就用 7.6；反之，你删了全局 Gradle，./gradlew 照样能跑——只要 wrapper 配置正确、网络能下载对应二进制。
立即学习“Java免费学习笔记（深入）”；
在调试 Java 后端 API 故障时使用此技能，尤其适用于以下任务：分析日志、跨 Controller、Service 和 Mapper 层追踪请求、定位异常根因、检查 SQL 执行或参数流转，以及生成简洁的诊断结论与修复方案。
- 检查项目 wrapper 版本：打开
gradle/wrapper/gradle-wrapper.properties，看distributionUrl行，比如https\://services.gradle.org/distributions/gradle-7.6-bin.zip - 升级 wrapper：运行
./gradlew wrapper --gradle-version 8.10，会自动更新配置和 JAR 文件 - 不要为了“统一版本”强行删掉
gradlew改用全局gradle，CI/CD 和团队协作会立刻出问题
JAVA_HOME未识别：Gradle启动直接失败
运行 gradle -v 或 ./gradlew 报错 Could not determine java version from '21.0.3' 或更常见的 No Java runtime present，大概率是 JAVA_HOME 指向了 JRE、或指向了 JDK 但 bin 下缺 java 可执行文件。
Gradle 8.x 要求 JDK 17+，且必须是完整 JDK（含 javac），不能是仅含 java 的 JRE。Mac 用户尤其容易中招——系统自带的 /usr/libexec/java_home 返回路径可能指向 JRE。
- 验证
JAVA_HOME是否有效：执行$JAVA_HOME/bin/java -version和$JAVA_HOME/bin/javac -version，两个都得成功输出 - macOS 推荐用
export JAVA_HOME=$(/usr/libexec/java_home -v 17)（指定版本），避免默认指向旧版或 JRE - Windows 用户注意路径斜杠方向，
JAVA_HOME值里不能有中文、空格，否则 Gradle 启动脚本解析会崩
Gradle daemon卡住或内存爆掉：堆大小没调
执行 ./gradlew build 卡在 “Starting Daemon…” 或构建中途 OOM，不是网络问题，是 daemon 进程默认堆太小（通常 512MB），尤其在多模块、Kotlin、Android 项目里很容易顶满。
这个配置不在 gradle.properties 全局文件里写 org.gradle.jvmargs 就完事——它只影响新启动的 daemon，已驻留的旧 daemon 不会 reload 参数，得先 kill 掉。
- 改配置：在
~/.gradle/gradle.properties（用户级）或项目根目录下gradle.properties（项目级）加一行：org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m - 清旧 daemon：运行
./gradlew --stop，再执行构建，确保新参数生效 - Android 项目建议额外加
-XX:+HeapDumpOnOutOfMemoryError，OOM 时自动生成堆转储，方便定位哪块吃内存
环境变量这事，最麻烦的从来不是“怎么配”，而是配完不知道它到底被谁读、被谁忽略、被谁覆盖。多一个 echo $JAVA_HOME，少一次重启 IDE，真省半小时。
