gradlew 能强制统一 Gradle 版本，因其绕过本地 PATH，读取项目内 gradle-wrapper.properties 中的 distributionUrl，从 ~/.gradle/wrapper/dists/ 下载或复用对应版本缓存，不依赖系统已安装的 Gradle。
为什么 gradlew 能强制所有人用同一个 Gradle 版本
因为 gradlew 不调用你本地 PATH 里的 Gradle，而是读取项目内 gradle/wrapper/gradle-wrapper.properties 中的 distributionUrl，然后去 ~/.gradle/wrapper/dists/ 查对应版本缓存。没缓存就下载，有缓存就直接启动——整个过程完全绕过系统已安装的 Gradle。
这意味着：哪怕你机器上装着 Gradle 6.8、7.6、8.5 三个版本，只要执行 ./gradlew build，它就只认配置文件里写的那个版本，不会“误用”其他版本。
- 团队成员 clone 代码后无需配置环境变量或手动安装 Gradle
- CI/CD 流水线服务器不用预装任何 Gradle，直接跑
./gradlew test即可 - 版本变更只需改一行
distributionUrl=https://services.gradle.org/distributions/gradle-8.5-bin.zip，提交即可生效
哪些文件必须提交到 Git 才能保证统一
只有这四个文件纳入版本控制，Wrapper 才能真正起作用：
-
gradlew（Linux/macOS 可执行脚本） -
gradlew.bat（Windows 批处理脚本） -
gradle/wrapper/gradle-wrapper.jar（负责解析和下载的核心 JAR） -
gradle/wrapper/gradle-wrapper.properties（含distributionUrl的关键配置）
漏掉任意一个，比如只提交了 .properties 却忘了 gradle-wrapper.jar，新成员执行 ./gradlew 会直接报错：Could not execute java: No such file or directory —— 因为脚本找不到 jar 来启动 JVM。
常见错误：明明改了 distributionUrl，为什么还是用旧版本
根本原因不是配置没生效，而是本地缓存没清或脚本没重生成。Gradle Wrapper 启动时只校验 ~/.gradle/wrapper/dists/ 下有没有匹配 distributionUrl 解析出的目录名（比如 gradle-8.5-bin/xxx...），不校验内容是否最新。
- 如果之前下过
gradle-8.4-bin，现在改成8.5，但没删旧缓存，它仍可能复用旧目录里的二进制（尤其当网络失败又 fallback 到本地已有解压包时） - 更隐蔽的问题：
gradle-wrapper.jar本身也有版本逻辑，老 jar 可能不支持新distributionUrl格式（如带-all后缀或新版 checksum 验证） - 正确做法是：改完
gradle-wrapper.properties后，运行./gradlew wrapper --gradle-version 8.5重新生成全套 wrapper 文件，再提交
AGP 和 Gradle 版本不匹配时，wrapper 还管用吗
管用，但会构建失败——wrapper 确保了 Gradle 版本统一，但不能自动修复 AGP 兼容性问题。比如 android-gradle-plugin 8.2.0 要求最低 Gradle 8.2，如果你在 gradle-wrapper.properties 里配了 gradle-8.1-bin.zip，./gradlew build 会明确报错：The Android Gradle plugin supports only Gradle 8.2 and higher。
所以团队统一的第一步是锁 Gradle，第二步必须同步更新 build.gradle 里的 com.android.tools.build:gradle 版本，并查官方 AGP-Gradle 兼容表。两者缺一不可。
最容易被忽略的是：wrapper 锁死 Gradle 版本后，开发者反而更容易忽略 AGP 升级带来的破坏性变更，比如 Gradle 8.4 开始默认启用 configuration cache，而旧版 AGP 可能未适配，导致 ./gradlew assembleDebug 直接失败。这种问题不会出现在 “本地装 Gradle” 场景里，因为大家版本乱，反而不敢开新特性；但 wrapper 一统江湖后，所有人在同一时刻撞上同一个坑。
