所有人必须使用./gradlew（Linux/macOS）或gradlew.bat（Windows），不可调用本地gradle命令；Wrapper将Gradle版本锁定在项目中，确保统一构建逻辑：需检查gradlew/gradlew.bat、gradle/wrapper/gradle-wrapper.jar、gradle/wrapper/gradle-wrapper.properties三者齐全且distributionUrl为https开头并以-bin.zip结尾；生成或升级时执行gradle wrapper --gradle-version X.X，且必须提交全部Wrapper文件至Git；IDE和CI均须配置为使用Wrapper而非本地Gradle。
核心就一条：所有人只用 ./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 版本，就在项目根目录运行：
-
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 官方兼容表，再调整JAVA_HOME或build.gradle中的java { toolchain }
