Java项目中必须统一使用gradlew或gradlew.bat执行构建，禁止调用本地gradle命令；需确保项目根目录含gradlew/gradlew.bat、gradle/wrapper/gradle-wrapper.jar和gradle-wrapper.properties（含distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip），三者缺一不可，且生成后须全部提交Git。
Java 项目中用 Gradle Wrapper 保证团队环境一致，核心就一条：所有人只用 ./gradlew（Linux/macOS）或 gradlew.bat（Windows），不碰本地安装的 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，或需要升级 Gradle 版本，就在项目根目录运行：
立即学习“Java免费学习笔记（深入）”；
-
推荐写法：
gradle wrapper --gradle-version 8.5（显式指定版本，避免依赖本地版本偏差） - 生成后，必须把
gradlew、gradlew.bat和整个gradle/wrapper目录提交到 Git —— 这是统一环境的前提 - 不要手动改
gradle-wrapper.jar，它和distributionUrl必须严格匹配；改 URL 时只动这一行，结尾必须是-bin.zip，协议必须是https
所有场景都走 Wrapper 脚本
无论谁操作、在哪执行，都要用 Wrapper：
-
命令行：Linux/macOS 用
./gradlew build，Windows 用gradlew.bat test - IDE（如 IntelliJ）：设置 Gradle JVM 为项目 JDK，Gradle user home 保持默认，关键是要选 “Use gradle wrapper task configuration”，而不是 “Bundled Gradle” 或 “Local installation”
-
CI/CD（GitHub Actions、GitLab CI）：流水线脚本直接写
./gradlew build，不用额外装 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 官方兼容表，比如 Gradle 8.5 要求 JDK 17–21
