distributionUrl配置需严格遵循协议、路径格式、文件存在性及校验机制四重约束：Windows用file:///d:/...，macOS/Linux用file:///path；必须正斜杠、无空格中文；改后需手动清理wrapper/dists下对应哈希目录并验证校验值。
distributionUrl 配置错一个字符，Gradle 就会重下一遍、卡在 “Downloading gradle-xx-bin.zip”、甚至报 Connection refused 或 Invalid url —— 它不是简单的“填个链接”，而是受协议、路径格式、文件存在性、校验机制四重约束。
file:// 协议本地路径怎么写才不报错
Windows 和 macOS/Linux 的路径写法差异极易翻车，尤其斜杠方向和盘符处理：
必须用正斜杠 /，哪怕在 Windows 上也禁用反斜杠 \
Windows 绝对路径要加三个前导斜杠：file:///d:/dev-tools/gradle/gradle-8.10-bin.zip
macOS/Linux 路径从根开始，开头是 file:///，不是 file://（少一个 / 会静默失败）
路径中不能有空格或中文（某些 Gradle 版本会解析失败），建议用短英文路径如 /opt/gradle/
ZIP 文件必须真实存在且可读；若用符号链接，确保目标文件权限正常
为什么改了 distributionUrl 还是联网下载
Gradle Wrapper 不会自动清旧缓存，它只看 distributionPath 下有没有对应解压目录（如 gradle-8.10-bin/5x8q9v2y6z7m3n4p1r2s5t6u7v8w9x0），而不是校验 distributionUrl 是否变了：
手动删掉 GRADLE_USER_HOME/wrapper/dists/ 下对应版本的整个文件夹（含哈希子目录）
确认 gradle-wrapper.properties 中 distributionBase 和 distributionPath 没被意外覆盖（默认是 GRADLE_USER_HOME + wrapper/dists）
运行 ./gradlew --version 触发检查；不要依赖 IDE 同步按钮，它有时跳过 Wrapper 初始化
如果项目里有 gradle/wrapper/gradle-wrapper.jar，确保它和 distributionUrl 指向的 Gradle 版本兼容（例如 8.x 的 wrapper.jar 不能拉 7.x 的 zip）
用镜像源时 URL 转义和版本匹配要点
国内镜像虽快，但不是所有镜像都同步及时，且 distributionUrl 中的 / 必须转义为 \（这是 Java Properties 文件规范，不是 Gradle 特有）：
阿里云镜像正确写法：distributionUrl=https\://mirrors.aliyun.com/gradle/gradle-8.10-bin.zip
腾讯云镜像示例：distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.10-all.zip
-bin.zip 足够日常构建，-all.zip 多出文档和源码，体积大、解压慢，CI 环境慎用
镜像站未必提供所有版本；查不到时去官网确认该版本是否存在，再找对应镜像路径（比如 gradle-8.10.2-bin.zip 可能还没上镜像）
部分镜像不支持 HTTPS 重定向，遇到 Received fatal alert: protocol_version 可临时换回官方地址排查
要不要加 distributionSha256Sum 校验
加，尤其是用本地路径或非官方镜像时——distributionSha256Sum 是唯一防止 ZIP 文件损坏或被篡改的机制，Gradle 8.4+ 默认强制校验：
生成方式：用命令行算哈希，例如 shasum -a 256 gradle-8.10-bin.zip（macOS/Linux）或 CertUtil -hashfile gradle-8.10-bin.zip SHA256（Windows）
值要粘贴完整（64位小写十六进制字符串），末尾不能有多余空格
一旦配置了 distributionSha256Sum，但值不匹配，Gradle 会直接失败并提示 Checksum verification failed，不会退回到不校验模式
离线环境尤其依赖它：没网络时，只有校验通过才会继续解压执行，否则停在下载阶段
本地路径看似一劳永逸，但真正稳定要用好，得同时管住路径格式、缓存清理、校验开关和文件权限。很多人卡在第一步“路径写对了却还是下”，其实是第二步缓存没清干净。
