Gradle Wrapper 是 Java 项目的标准实践，通过 gradlew 脚本自动下载并使用项目指定版本的 Gradle，避免环境不一致和版本冲突；手动安装全局 Gradle 易导致兼容性问题，CI/CD 和 IDE 均应配置为使用 Wrapper。
Gradle 不需要单独“安装”，Java 项目里用的是 Gradle Wrapper（gradlew），它自带 Gradle 运行时，避免环境不一致问题。手动装 gradle 命令行工具反而容易和项目要求的版本冲突。
为什么不用 brew install gradle 或手动配置 GRADLE_HOME
多数 Java 项目根目录下已有 gradlew（Linux/macOS）或 gradlew.bat（Windows）——这是 Wrapper 脚本，会自动下载并缓存指定版本的 Gradle（版本由 gradle/wrapper/gradle-wrapper.properties 中的 distributionUrl 决定）。硬装全局 Gradle：
- 可能和项目
gradle-wrapper.properties要求的版本不兼容（比如项目要 8.4，你装了 8.9，某些插件会报Incompatible version） - CI/CD 流水线、同事本地构建行为不一致
-
./gradlew build会忽略你本地的gradle命令，仍走 Wrapper
如何确认项目是否已启用 Wrapper
检查以下文件是否存在且内容合理：
-
gradlew（Unix 可执行脚本）或gradlew.bat（Windows 批处理） gradle/wrapper/gradle-wrapper.jar-
gradle/wrapper/gradle-wrapper.properties，其中应含类似：distributionUrl=https\://services.gradle.org/distributions/gradle-8.4-bin.zip
如果缺失，运行 gradle wrapper --gradle-version 8.4（需本地有临时可用的 Gradle）生成；但更推荐从项目源码完整拉取，而非手动补。
立即学习“Java免费学习笔记（深入）”；
IDE（IntelliJ / Eclipse）里怎么配才不踩坑
IDE 默认会识别 gradlew 并用它同步项目，但常见错配点：
- IntelliJ：不要在
Settings > Build > Build Tools > Gradle里选Use gradle from module SDK—— 它根本不存在；应选Use Gradle from wrapper - Eclipse + Buildship：导入项目时勾选
Use Gradle wrapper，别选Use installed Gradle - 若 IDE 报
Unsupported Java version，不是 Gradle 版本问题，而是检查gradle.properties是否设了org.gradle.java.home，或项目build.gradle中java.toolchain.version是否匹配你装的 JDK
遇到 Could not determine java version from 'XX.X' 怎么办
这是 Gradle Wrapper 启动时解析 java -version 输出失败，常见于较新 JDK（如 JDK 21+）或自定义 JDK 构建版。解决方式：
- 升级 Wrapper：修改
gradle-wrapper.properties的distributionUrl到支持该 JDK 的 Gradle 版本（例如 JDK 21 推荐 Gradle ≥ 8.0） - 临时降级 JDK：用
java -version输出格式稳定的 JDK（如 17.0.2）跑一次./gradlew --version，Wrapper 缓存建立后，再换回新版 JDK - 不推荐改
JAVA_HOME指向旧 JDK 全局生效——会影响其他项目
Wrapper 是约定，不是可选项。跳过它去配全局 Gradle，等于主动放弃构建可重现性。
