错误根源是distributionurl指向的gradle zip文件下载不完整或损坏，常见于网络中断、gfw干扰或杀软误删，导致文件大小异常（如仅几十kb而非200mb+），解压时因缺失end header而报错。
gradle-wrapper.properties里指定的zip文件打不开
错误日志里明确出现 java.util.zip.ZipException: error in opening zip file，基本可以锁定是 gradle-wrapper.properties 中 distributionUrl 指向的 ZIP 文件损坏。这个 ZIP 不是项目代码的一部分，而是 Gradle Wrapper 自动下载并缓存在本地的构建工具本体。
常见表现包括：
- Android Studio 同步卡在 “Downloading gradle-x.x-all.zip” 后报错
- UE5 打包 Android 时在解压阶段崩溃
- 命令行执行
./gradlew build直接抛出 ZipException
根本原因通常是网络中断、GFW干扰或防病毒软件误删导致下载不完整——你看到的 gradle-7.6-all.zip 文件大小可能只有几十 KB，而正常应为 200MB+。
手动验证并替换损坏的gradle-*.zip文件
别急着删整个 .gradle 缓存目录，先精准定位和验证：
- 从错误日志中提取完整路径，例如：
C:\Users\name\.gradle\wrapper\dists\gradle-7.6-all\425158m1g42x005f3z2hjv92q\gradle-7.6-all.zip - 用资源管理器进入该目录，右键点击 ZIP 文件 → “属性”，确认文件大小是否明显偏小（如
- 用 7-Zip 或 WinRAR 尝试打开它，若提示“文件损坏”或“无法读取压缩包”，即确认损坏
- 访问
https://services.gradle.org/distributions/，手动下载**完全同名**的 ZIP（注意 URL 是 https，不是 http） - 关闭 Android Studio / UE5 / 终端等所有可能占用该文件的进程，将新下载的 ZIP **直接覆盖**到上述路径下（不要解压！）
下次运行构建时，Wrapper 会自动检测并解压这个完整 ZIP——只要文件名和路径完全一致，无需改任何配置。
为什么不能直接删.gradle/wrapper/dists然后重下
看起来最省事，但实际容易踩坑：
- 重下过程仍走
services.gradle.org，国内网络大概率再次中断或超时 - 某些旧版 UE5 或 Hippy 项目硬编码了特定 Gradle 版本（如
gradle-6.1.1-all），新版 Gradle 可能与 AGP 或引擎不兼容 - 删 dists 后首次构建会卡在下载，期间若被杀进程或断网，又生成一个半成品 ZIP，问题复现
- Gradle Wrapper 的校验逻辑对部分损坏 ZIP 不敏感，可能跳过完整性检查直接尝试解压，结果还是失败
所以，离线下载 + 精准替换，比依赖自动重试更可靠。
gradlew脚本找不到wrapper任务？其实是Wrapper本身缺失
如果错误是 Task 'wrapper' not found，那不是 ZIP 损坏，而是项目根目录压根没有 Gradle Wrapper 文件。这种情况多见于：
- Git clone 时忽略了
.gitignore里的gradle/目录 - 从 ZIP 包解压的开源项目，作者没把
gradlew和gradle/wrapper/一起打包 - Hippy、React Native 等跨端框架的示例工程常有此问题
修复方法很简单：在项目根目录运行
./gradlew wrapper --gradle-version 7.6 --distribution-type all
这条命令会生成完整的 Wrapper 文件集（gradlew, gradle/wrapper/ 等）。注意版本号必须与项目 gradle-wrapper.properties 里要求的一致，否则后续同步仍会触发下载。
真正麻烦的不是 ZIP 损坏本身，而是它常和网络、权限、IDE 缓存耦合在一起——单点修复后，最好顺手关掉实时杀毒软件的文件监控，再试一次。否则刚放进去的新 ZIP，可能又被拦截写坏。
