应优先用 curl/wget 直接测试 distributionUrl 可访问性，还原转义 URL 后执行 curl -I 或 GET 请求；对镜像需加 -L 处理重定向，file 协议则用 ls 和 file 命令验证文件存在性与格式；Gradle Wrapper 日志不暴露底层网络异常，需加 -Djavax.net.debug=ssl:handshake 等 JVM 参数调试；distributionSha256Sum 校验失败时须严格比对 ZIP 文件与配置中版本一致性，并用系统命令重算哈希值；Android Studio Sync 卡住常因未实际启用 wrapper，需确认 gradlew 存在、权限正常，并清除 .idea/misc.xml 中残留配置，最终以 ./gradlew -v 输出为准。
直接用 curl 或 wget 测试 distributionUrl 是否可访问
别等 ./gradlew 报错再排查——那个错误信息太笼统，比如 Could not download gradle-8.3-all.zip，根本看不出是 DNS、证书、代理还是 URL 拼写的问题。最简单有效的方式，就是把 distributionUrl 里的地址抠出来，手动发起一次 HTTP HEAD 或 GET 请求。
注意两点：一是 URL 里有反斜杠转义（https\://），得先还原成 https://；二是如果用了镜像站或本地 file 协议，行为完全不同。
- 官方地址（如
https://services.gradle.org/distributions/gradle-8.3-all.zip）：用curl -I -f -s -o /dev/null https://services.gradle.org/distributions/gradle-8.3-all.zip，返回 200 表示可访问，404 表示版本不存在，403/503 多半是网络策略拦截 - 镜像地址（如阿里云）：同样测试，但要注意有些镜像不支持 HEAD，得加
-L跟重定向，且首次响应可能是 302 - 本地 file 协议（如
file:///opt/gradle/gradle-8.3-all.zip）：用ls -l /opt/gradle/gradle-8.3-all.zip看文件是否存在、权限是否可读，file命令确认是不是 ZIP 格式，别让路径里混入空格或中文
为什么 gradle wrapper --debug 还是看不到真实下载失败原因
./gradlew --debug 日志里确实会打印 “Downloading …”，但实际网络层的异常（比如 TLS 握手失败、proxy auth required、证书过期）往往被 Gradle 的封装逻辑吞掉，只留下一句 Failed to download。它默认不暴露底层 java.net.HttpURLConnection 或 OkHttp 的原始异常栈。
真正有用的调试方式是加 JVM 参数强制输出网络细节：
- Linux/macOS：
./gradlew -Djavax.net.debug=ssl:handshake --debug build - Windows：
gradlew.bat -Djavax.net.debug=ssl:handshake --debug build - 如果怀疑是代理问题，额外加
-Dhttp.proxyHost=xxx -Dhttp.proxyPort=xxx
这时候你会看到 SSL 握手过程、DNS 解析结果、甚至服务器返回的完整 HTTP 响应头——比看 Wrapper 日志靠谱得多。
distributionSha256Sum 校验失败时，怎么快速定位是哪一环出问题
这个字段不是“锦上添花”，而是离线部署时的兜底开关。一旦配置了 distributionSha256Sum，Gradle 就会在解压前校验 ZIP 文件完整性。失败只有两种可能：文件损坏，或 checksum 值本身写错了。
验证步骤非常直白：
- 先确认你用的是和
distributionUrl完全匹配的 ZIP 文件（比如 URL 是gradle-8.3-all.zip，就别拿gradle-8.3-bin.zip去算） - 用系统命令重算一遍：
shasum -a 256 gradle-8.3-all.zip（macOS/Linux）或CertUtil -hashfile gradle-8.3-all.zip SHA256（Windows） - 对比输出和
gradle-wrapper.properties里写的值——注意大小写、空格、换行符。很多失败是因为复制时多了一个不可见的\r或粘贴进去了全角字符
如果校验值对不上，别改 properties 文件去凑，优先重下 ZIP 文件。checksum 是防篡改用的，不是兼容性开关。
Android Studio 里点 Sync 还是卡住？检查它根本没走 wrapper 配置
很多人以为改了 gradle-wrapper.properties 就万事大吉，结果 Android Studio 同步时依然去外网拉包，或者报错说 “No such file or directory” ——其实 IDE 可能压根没读这个配置。
常见原因有三个：
- 项目根目录下没有
gradlew和gradle/wrapper/目录，AS 就会 fallback 到全局 Gradle 设置（File → Settings → Build → Build Tools → Gradle → Gradle JDK / Gradle user home） -
gradle/wrapper/目录权限不对，比如 Windows 上 Git Bash 创建的文件夹被 AS 以管理员身份读取失败 - AS 缓存了旧的 wrapper 配置，关掉项目、删掉
.idea/misc.xml里关于gradleSettings的残留项，再重新打开
最稳的验证方式：在终端里进项目根目录，执行 ./gradlew -v，看输出的 Gradle 版本和路径。如果这里都对，但 AS 还不对，那一定是 IDE 层级的配置覆盖了 wrapper。
