java项目应使用gradle wrapper而非手动安装gradle，通过gradlew脚本、gradle-wrapper.jar和gradle-wrapper.properties锁定版本，确保团队构建一致；缺失任一文件需运行gradle wrapper --gradle-version 8.5生成并提交至git。
Java 项目里不需要手动“安装 Gradle”，正确做法是用 Gradle Wrapper —— 它把构建工具版本锁死在项目中，所有人执行同一个命令，就用同一个 Gradle 版本。
确认项目已启用 Wrapper
打开项目根目录，检查是否存在以下文件：
- gradlew（Linux/macOS 可执行脚本）或 gradlew.bat（Windows 批处理）
- gradle/wrapper/gradle-wrapper.jar
-
gradle/wrapper/gradle-wrapper.properties，其中包含类似这行：
distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip
三者齐全，说明 Wrapper 已就位。缺任何一项，后续构建会失败或绕过版本控制。
生成或更新 Wrapper（如需）
如果项目没提供 Wrapper，或需要升级 Gradle 版本，就在项目根目录运行：
-
gradle wrapper --gradle-version 8.5（推荐，前提是本地临时有能跑的 Gradle，建议 ≥ 8.0） - 不指定参数时，默认用当前本地 Gradle 版本生成，但容易引入偏差，所以务必显式指定版本
- 生成后，必须把 gradlew、gradlew.bat 和整个 gradle/wrapper 目录提交到 Git——这是保证团队一致的关键动作
统一使用 Wrapper 命令
所有构建操作都走 Wrapper 脚本，不调用全局 gradle 命令：
- Linux/macOS：
./gradlew build、./gradlew test - Windows：
gradlew.bat build、gradlew.bat test - IDE（如 IntelliJ）也应配置为使用
gradlew，而非“Bundled Gradle”或本地安装路径 - CI/CD（GitHub Actions、GitLab CI）默认只认
./gradlew，不会预装任何 Gradle
验证和排查常见问题
运行 ./gradlew --version 查看实际生效的 Gradle 版本，它应与 gradle-wrapper.properties 中 distributionUrl 的版本号完全一致。
- 报错
Could not find or load main class org.gradle.wrapper.GradleWrapperMain：基本是gradle-wrapper.jar和distributionUrl版本不匹配，或 URL 里多了空格、用了 http、结尾不是-bin.zip - 报错
Could not determine java version from 'XX.XX.X'：说明 JDK 版本与该 Gradle 版本不兼容，查 Gradle 官方兼容表，再调整JAVA_HOME或build.gradle中的java { toolchain } - 修改
gradle-wrapper.properties后无需重装，下次运行./gradlew就会自动拉取新版本并缓存
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
