Gradle的distributionSha256Sum校验时机是什么时候？
2026-5-28
Gradle Wrapper的distributionSha256Sum校验时机详解
嘿，这个问题我之前踩过坑，来给你把逻辑说清楚～
Gradle Wrapper的distributionSha256Sum哈希校验只有在需要下载Gradle分发包的时候才会触发，不是每次构建都会校验，这就是你改了哈希甚至删了项目根目录.gradle还没报错的原因。具体分这几种情况：
首次使用某版本Gradle，或本地无对应缓存时：
当你的机器上（包括项目本地缓存和全局缓存）没有该版本的Gradle分发包，Wrapper会自动从distributionUrl指定的地址下载，这时候就会对比下载文件的SHA256哈希和你配置的distributionSha256Sum是否一致。如果不匹配，会直接抛出错误终止构建。本地已有对应版本缓存时：
只要Gradle能找到本地缓存的对应版本（不管是项目根目录的.gradle/wrapper/dists，还是用户全局目录下的.gradle/wrapper/dists），它就会直接复用缓存，完全不会去校验distributionSha256Sum——哪怕你把哈希改成完全错误的值也没用。你删除项目
.gradle没报错的原因：
你删掉的只是项目根目录下的.gradle，但Gradle的全局缓存通常存在用户目录里：- Windows：
C:\Users\<你的用户名>\.gradle\wrapper\dists - macOS/Linux：
~/.gradle/wrapper/dists
只要这个全局缓存里还有对应版本的Gradle，Wrapper就会直接用它，不会触发下载和校验。
- Windows：
怎么验证哈希校验是否生效？
你可以试这两个方法：
- 彻底删除全局缓存里对应版本的Gradle文件夹，然后重新构建——这时候Wrapper会重新下载，错误的哈希就会触发报错。
- 修改
gradle-wrapper.properties里的distributionUrl为一个你本地没有的Gradle版本（比如把7.5改成7.6），同时把distributionSha256Sum改成错误的值，构建时就会触发下载并校验，直接报错。
另外补充个小细节：在CI/CD环境里，因为每次都是全新环境没有缓存，所以每次构建都会下载Gradle并校验哈希，这时候错误的哈希会立刻暴露出来。
内容的提问来源于stack exchange，提问作者ligi
