直接写file:///加绝对路径可跳过网络下载，Windows用file:///C:/.../gradle-x.x-x.zip，macOS/Linux用file:///Users/.../gradle-x.x-x.zip，路径须全英文无空格，末尾必须带.zip，且三个斜杠不可少。
gradle-wrapper.properties 里 distributionUrl 怎么写本地路径
直接写 file:// 协议绝对路径就能跳过网络下载，但必须严格匹配 ZIP 文件实际存放位置。Windows 和 macOS/Linux 路径写法不同，且不能漏掉末尾的 .zip 后缀。
- macOS/Linux 示例：
distributionUrl=file:///Users/yourname/.gradle/wrapper/dists/gradle-8.6-all/manual/gradle-8.6-all.zip - Windows 示例：
distributionUrl=file:///C:/Users/yourname/.gradle/wrapper/dists/gradle-8.6-all/manual/gradle-8.6-all.zip - 路径中不能有空格或中文（否则部分 Gradle 版本会解析失败）
-
file://后面是三个斜杠（///），不是两个；第一个是协议分隔符，后两个是绝对路径起始
为什么手动放 ZIP 到 .gradle/wrapper/dists/ 目录后，用官方 URL 还是会重下
Gradle Wrapper 不是“看到目录存在就跳过”，而是检查 distName/versionHash/gradle-x.x.x-all.zip 是否完整、是否通过校验。如果只是把 ZIP 放进 gradle-x.x.x-all/ 子目录，但没放进带随机哈希的二级子目录（比如 4x0529s1f2q8z7v9w3t6m5n1r4），它就会当作未缓存，重新下载。
- 正确结构必须是：
.gradle/wrapper/dists/gradle-8.6-all/4x0529s1f2q8z7v9w3t6m5n1r4/gradle-8.6-all.zip - 哈希值由 Gradle 自己生成，不能手写；可用
gradlew --version触发一次失败下载，观察日志里打印出的真实哈希路径，再把 ZIP 放进去 - 或者干脆跳过这层——直接用
file://路径，完全绕开哈希校验逻辑
GRADLE_USER_HOME 和 wrapper 缓存路径的关系
GRADLE_USER_HOME 环境变量决定了全局缓存根目录，默认是 ~/.gradle。Wrapper 所有下载行为都基于它，所以改这个变量会影响所有项目的本地发行包存放位置。
- 想统一团队缓存路径？在每台机器上设
GRADLE_USER_HOME=/opt/gradle-cache，然后所有file://路径都要按这个新根来写 - 不建议把
GRADLE_USER_HOME指向 NFS 或慢速网络盘——解压和加载 JAR 会明显变卡 - Android Studio 的 Settings → Build → Build Tools → Gradle 里显示的 “Gradle user home” 就是这个值，改完要重启 IDE 生效
用本地发行包时，gradlew 启动失败的常见报错
最典型的是 Could not find or load main class org.gradle.wrapper.GradleWrapperMain，说明 gradle-wrapper.jar 本身损坏，或与本地 ZIP 版本不匹配。
- 检查
gradle/wrapper/gradle-wrapper.jar是否被意外替换过；建议从同版本 Gradle 官方包里重新提取一份 - 确认
gradle-wrapper.properties中的distributionUrl指向的 ZIP 名称，和你实际下载的文件名完全一致（比如gradle-8.6-all.zip≠gradle-8.6-bin.zip） - Java 版本不兼容也会触发类似错误：Gradle 8.6 要求 JDK 17+，如果
gradlew启动时用了 JDK 11，它甚至不会尝试解压 ZIP，直接报类找不到
gradlew 就不会再碰网络。但很多人卡在“以为放对了路径”，其实哈希目录或协议写法差了一点点。 
