CI节点上Gradle Wrapper重复下载，是因为每次执行gradlew时均检查~/.gradle/wrapper/dists/下对应版本解压目录是否存在，而CI环境常因容器重建、工作区清理导致该路径被清空，且distributionUrl未变更时仍触发重新下载；绕过网络下载需预置ZIP及校验文件、配置CI缓存或改用file://协议，但必须确保SHA-256校验一致且路径哈希匹配当前distributionUrl。
CI 构建节点上 Gradle Wrapper 为什么还会重复下载
因为默认行为就是如此：gradlew 每次执行时，会检查 ~/.gradle/wrapper/dists/ 下是否存在对应版本的解压目录（如 gradle-8.6-all/xxx...），但这个检查依赖两个前提：一是该路径必须可写且未被清理；二是 gradle-wrapper.properties 中的 distributionUrl 指向的 ZIP 文件名和校验值没变。CI 环境常因容器重建、工作区清理或缓存策略缺失，导致 ~/.gradle/wrapper/dists/ 被清空或不可复用，于是每次构建都重新下载 gradle-8.6-all.zip —— 即使你已在前一次构建中下完并解压过。
让 CI 复用本地发行包的三种实操方式
核心思路是绕过网络下载环节，把已有的 gradle-8.6-all.zip 或其解压结果“塞进” Wrapper 期望的路径结构里，并确保校验通过。以下方式按推荐度排序：
- 在 CI 启动阶段预置完整 ZIP 到
~/.gradle/wrapper/dists/对应子目录（如gradle-8.6-all/5z9g2v8x7f3q1j4k2m5n6p7r8s9t0u1v/），目录名需匹配 Wrapper 计算出的哈希值（可用./gradlew --version触发一次失败下载，看日志里提示的预期路径） - 改用
distributionBase=GRADLE_USER_HOME+zipStoreBase=GRADLE_USER_HOME，再把整个~/.gradle/wrapper/dists/设为 CI 缓存路径（GitHub Actions 的actions/cache、GitLab CI 的cache:key:paths都支持） - 直接替换
gradle-wrapper.properties中的distributionUrl为file:///path/to/gradle-8.6-all.zip，但要注意：该路径必须对所有构建步骤可见，且 ZIP 文件权限需可读；不推荐用于跨平台 CI
校验失败是复用失败最隐蔽的原因
Wrapper 不只比对文件是否存在，还会校验 ZIP 的 SHA-256 值。如果你手动放了一个 ZIP 进去但没配对校验值，它会删掉你放的、再重下。校验值存在 ~/.gradle/wrapper/dists/gradle-8.6-all/xxx.../gradle-8.6-all.zip.sha256 文件里。常见错误包括：
- 从非官方渠道下载的
gradle-8.6-all.zip，SHA-256 与官方不一致 - 用
curl -O下载时被代理或 CDN 缓存污染，导致文件损坏 - CI 缓存恢复后，
.sha256文件丢失或内容为空
验证方式很简单：shasum -a 256 gradle-8.6-all.zip 输出是否和官方发布页标注的一致；再确认同目录下 .sha256 文件内容就是该输出值。
Android Studio 本地开发机的缓存不能直接拷给 CI
虽然你本机 ~/.gradle/wrapper/dists/ 里已有 gradle-8.6-all 完整目录，但别直接 tar.gz 打包扔进 CI。原因有二：
- 目录名中的哈希串（如
5z9g2v8x7f3q1j4k2m5n6p7r8s9t0u1v）是根据distributionUrl字符串计算的，CI 中若distributionUrl是https://services.gradle.org/...，而你本地是镜像源地址，哈希就不匹配 - 解压后的
bin/gradle脚本里硬编码了绝对路径（如GRADLE_HOME），在 CI 容器里可能失效
真正安全的做法，是只搬运原始 ZIP 文件 + 对应的 .sha256，让 Wrapper 自己解压 —— 它生成的路径和脚本都是动态适配当前环境的。
