Gradle Wrapper 自6.8起支持distributionSha256Sum校验，需在gradle-wrapper.properties中填写64位十六进制SHA256值（如distributionSha256Sum=8a7f3b1e9c2d...），由gradlew脚本下载后自动验证完整性；若未报错，可能是脚本版本过低或校验未触发。
Gradle Wrapper 的 gradle-wrapper.properties 里怎么填 SHA256 校验值
Gradle Wrapper 本身不自动校验下载包的 SHA256，但自 Gradle 6.8 起支持在 gradle-wrapper.properties 中声明 distributionSha256Sum，由 gradlew 脚本执行时主动验证。没配这个字段，就等于跳过校验。
实操上，你需要：
- 从官方发布页（如 https://www.php.cn/link/1cbfa9c878ef8692c1ae21e4cfa11000）下载对应版本的二进制包（例如
gradle-8.10-bin.zip） - 用本地工具算出它的 SHA256 值：
shasum -a 256 gradle-8.10-bin.zip（macOS/Linux）或certutil -hashfile gradle-8.10-bin.zip SHA256（Windows） - 把结果（64 字符十六进制字符串）填入项目中的
gradle/wrapper/gradle-wrapper.properties，格式为：distributionSha256Sum=8a7f3b1e9c2d...
为什么加了 distributionSha256Sum 还不报错？可能根本没触发校验
Gradle Wrapper 只在校验失败时抛出明确错误（Verification failed for Gradle distribution），但如果它压根没去校验，就不会报错——常见原因有：
-
gradlew脚本版本太老（distributionSha256Sum 字段，直接忽略 - 本地已存在对应版本的解压目录（如
~/.gradle/wrapper/dists/gradle-8.10-bin/xxx/），Wrapper 默认跳过下载和校验 - 环境变量
GRADLE_OPTS或 JVM 参数干扰了 Wrapper 启动流程，导致校验逻辑被绕过
验证是否真正在校验：删掉本地缓存目录（rm -rf ~/.gradle/wrapper/dists/gradle-8.10-bin/），再运行 ./gradlew --version。此时必须走网络下载 + 校验，失败会立刻中断并打印错误。
distributionUrl 和 distributionSha256Sum 必须严格匹配
SHA256 不是通用签名，而是对 distributionUrl 指向的完整 ZIP 文件内容计算得出的。哪怕 URL 多一个斜杠、少一个 -bin 后缀，或用了镜像源地址，校验都会失败。
常见不匹配场景：
- 误把
gradle-8.10-all.zip的哈希填进gradle-8.10-bin.zip的配置里 - 用了国内镜像（如
https://mirrors.cloud.tencent.com/gradle/gradle-8.10-bin.zip），但哈希值仍照官网 ZIP 算——镜像站文件可能不同步或做了额外打包 - URL 中协议写成
http://（未加密），而实际下载重定向到https://，Wrapper 最终拉取的文件路径变了
稳妥做法：始终用官网 URL + 官网 ZIP 计算哈希，不要混用镜像源和官方哈希。
CI 环境下校验容易被静默跳过
很多 CI 流水线（GitHub Actions、GitLab CI）会预装 Gradle 或挂载缓存，导致 gradlew 直接复用已有安装，根本不读 distributionSha256Sum。这时候你以为的安全校验，其实形同虚设。
确保生效的关键动作：
- 在 CI 脚本开头显式清理 Wrapper 缓存：
rm -rf $HOME/.gradle/wrapper - 避免使用
actions/setup-java类 Action 自带的 Gradle 安装逻辑，改用纯./gradlew驱动 - 在 CI 日志里搜索关键词
Verifying distribution checksum（Gradle 7.4+ 输出），确认校验步骤真实执行
真正难的不是加一行哈希，而是让每个构建节点都强制走一遍校验链路——缓存、预装、网络策略，任何一个环节绕过去，SHA256 就只是配置文件里一段好看的字符串。
