1. Gradle Wrapper 初始化与版本锁定
为什么 Wrapper 是构建入口的第一道锁
新建 Android 工程时，真正决定“用哪个 Gradle 跑构建”的不是本机安装的 Gradle，而是工程根目录下的 gradle/wrapper/gradle-wrapper.properties。它把 Gradle 发行版版本、下载地址和校验和固化进仓库，团队与 CI 只要执行 ./gradlew，就会得到同一个构建入口。
Wrapper 由四个文件协同工作：gradlew（Unix 启动脚本）、gradlew.bat（Windows 启动脚本）、gradle-wrapper.jar（引导程序）和 gradle-wrapper.properties（版本与校验配置）。前三个负责“怎么启动”，最后一个负责“启动哪一个”。
生成 Wrapper 并锁定版本
如果本机已安装 Gradle，可在工程根目录执行以下命令生成 Wrapper，并指定目标版本：
gradle wrapper --gradle-version 8.7 --distribution-type bin执行后检查 gradle/wrapper/gradle-wrapper.properties，确认 distributionUrl 指向 gradle-8.7-bin.zip。随后计算该发行版的 SHA-256 校验和并写入配置：
# 下载发行版后计算校验和（示例命令）
sha256sum gradle-8.7-bin.zip
# 将结果写入 gradle-wrapper.properties
distributionSha256Sum=544c35d6bd849ae8a5ed0bcea39ba677dc25f77fdd4f09005e14cd36bd34cbe3校验和必须与
distributionUrl 指向的同一份发行版严格对应。版本升级时，两者必须同步更新，否则 Wrapper 会因校验失败而拒绝启动。验证锁定是否生效
执行 ./gradlew --version，输出中应显示 Gradle 8.7。若本机缓存中不存在该版本，Wrapper 会先下载并校验，校验通过后才启动构建。团队新成员克隆仓库后直接运行 ./gradlew assembleDebug，无需手动安装 Gradle。
CI 中应始终使用
./gradlew 而非系统 gradle 命令，并确保 gradle-wrapper.jar 已提交。若使用 Gradle 官方校验和，可从 https://services.gradle.org/distributions/ 对应版本的 .sha256 文件获取。可直接使用的配置模板
| 配置项 | 示例值 | 作用 |
|---|---|---|
distributionUrl | https\://services.gradle.org/distributions/gradle-8.7-bin.zip | 指定 Gradle 发行版版本与类型 |
distributionSha256Sum | 544c35d6...bd34cbe3 | 校验下载包完整性，防止篡改 |
distributionPath | wrapper/dists | 解压后存放路径（默认即可） |
zipStorePath | wrapper/dists | zip 缓存路径（默认即可） |
完成以上配置后，将 gradlew、gradlew.bat、gradle-wrapper.jar 和 gradle-wrapper.properties 一并提交到版本控制，即完成构建入口的统一锁定。