gradle解压失败主因是下载中断致zip损坏，需人工校验sha256并手动替换完整包；若启用distributionsha256sum校验，镜像包哈希不匹配会导致静默重试循环。
gradle-*.zip 解压失败的常见报错现象
执行 ./gradlew 或点击 Android Studio 的 Sync 时，控制台卡在 “Unzipping…” 后抛出类似错误：java.util.zip.ZipException: zip file is empty、invalid CEN header (bad signature)，或解压后目录下只有空文件夹、缺失 bin/gradle 可执行文件。这基本不是 Gradle 本身的问题，而是下载中断导致的 zip 文件损坏。
确认 .zip 文件是否完整（关键第一步）
Gradle Wrapper 不会校验下载文件的完整性，只管解压。所以必须人工验证：
- 打开
~/.gradle/wrapper/dists/（macOS/Linux）或C:\Users\{user}\.gradle\wrapper\dists\（Windows），找到对应版本的子目录，例如gradle-8.7-bin\7yzdu24db77gi3zukl2a7o0xx - 进入该目录，检查是否存在一个以
.zip结尾的文件，且大小明显异常（如仅几 KB）——这就是损坏包 - 对比官网或镜像站上同名 zip 的 SHA256 值（如阿里云镜像页会提供），用命令行校验：
shasum -a 256 gradle-8.7-bin.zip（macOS/Linux）或certutil -hashfile gradle-8.7-bin.zip SHA256（Windows）
手动替换 + 强制跳过下载的实操步骤
不要依赖重试，直接换包并绕过 Wrapper 的自动下载逻辑：
- 从可信镜像源（如
https://mirrors.cloud.tencent.com/gradle/或https://mirrors.aliyun.com/gradle/）下载完整 zip 包，注意后缀必须与gradle-wrapper.properties中distributionUrl完全一致（-bin.zip和-all.zip不可混用） - 将下载好的 zip 文件**直接复制**到上面查到的 hash 子目录中，覆盖已有的损坏文件
- 删除该 hash 子目录下的
gradle-8.7-bin.zip.lck（锁文件）和任何临时解压残留（如gradle-8.7-bin文件夹） - 运行
./gradlew --no-daemon --refresh-dependencies，加--no-daemon可避免后台进程干扰解压流程
distributionSha256Sum 校验失败的隐藏陷阱
如果项目启用了 validateDistributionUrl=true 且配置了 distributionSha256Sum，但你手动放的 zip 是从镜像站下载的，SHA256 值很可能不匹配——官方包和镜像包哈希不同是常态。此时有两种选择：
- 删掉
gradle-wrapper.properties中的distributionSha256Sum行（最简单，适合开发环境） - 用镜像站提供的 SHA256 值替换原值（需确认该镜像站明确声明“与官方一致”，腾讯云、阿里云通常不保证这点）
- 改用
https://services.gradle.org/distributions/直链下载（需配代理或换网络环境）
最容易被忽略的是：即使 zip 文件能正常解压，只要 distributionSha256Sum 校验失败，Gradle Wrapper 仍会静默删除已解压内容并重新尝试下载——整个过程不会报错，只会无限循环卡在 “Unzipping…”。
