distributionUrl必须写全版本号，因Gradle官方分发地址严格按完整语义化版本组织（如8.10.2），不支持模糊匹配；错误写法如gradle-8-bin.zip会导致404，引发下载失败或NoClassDefFoundError。
gradle-wrapper.properties 中的 distributionUrl 必须写全版本号
因为 Gradle 官方分发地址是严格按完整语义化版本（如 8.5、8.10.2）组织的，不支持模糊匹配或主版本通配。你写 distributionUrl=https://services.gradle.org/distributions/gradle-8-bin.zip，服务器根本不存在这个路径，HTTP 404 直接导致 ./gradlew 启动失败。
常见错误现象包括：Could not download gradle-wrapper.jar、Connection refused 或脚本执行时抛出 NoClassDefFoundError: org/gradle/wrapper/GradleWrapperMain —— 这些基本都是 URL 指向了不存在的归档包。
-
-bin.zip是必须的后缀，不能换成-all.zip或漏掉 - 版本号中不能有空格、中文、全角字符，也不能多加斜杠（如
//distributions/） - 必须用
https，部分企业网络会拦截http请求，导致下载中断 - AGP 8.6+ 要求 Gradle 8.9+，但如果你只写
8，它不会自动选8.9，而是直接报错退出
用 gradle wrapper 命令生成时，为什么有时仍要手动校验
命令 gradle wrapper --gradle-version 8.10.2 确实能自动生成正确的 gradle-wrapper.properties 和 gradle-wrapper.jar，但它依赖当前机器上已安装的 Gradle 版本能“驱动”该命令。如果本机装的是 Gradle 7.6，运行 --gradle-version 8.10.2 会失败：旧版 Gradle 的 Wrapper 生成器不认识新版的 distribution 结构。
所以实际流程往往是：
- 先用 SDKMAN 或手动安装一个较新的 Gradle（建议 ≥8.0）
- 在项目根目录下执行
gradle wrapper --gradle-version 8.10.2 - 立即检查生成的
gradle/wrapper/gradle-wrapper.properties：确认distributionUrl是https://services.gradle.org/distributions/gradle-8.10.2-bin.zip，且末尾无空格 - 删掉
gradle/wrapper/gradle-wrapper.jar后再跑一次./gradlew --version，验证是否真能拉取并启动 —— 这步能暴露网络代理、DNS 或防火墙问题
Android Studio 升级后 ./gradlew 报 Java 版本不兼容，跟 Wrapper 版本有关吗
有关，但不是 Wrapper 自身报错，而是它启动的 Gradle 实例被 JVM 拦截了。比如 Android Studio 2024.2（JBR 17）要求项目用 AGP 8.5+，而 AGP 8.5 要求 Gradle ≥8.6；但如果你的 gradle-wrapper.properties 还指向 gradle-7.5-bin.zip，那 ./gradlew build 会在启动阶段就抛 Unsupported class file major version 61（即 Java 17 字节码不被 Java 11 JVM 支持）。
这不是 Wrapper 配置错了，而是 Wrapper 拉起的 Gradle 运行时和当前 JDK 不匹配。解决路径很明确：
- 先确认 IDE 底层用的 JDK：File > Project Structure > SDK Location > JDK location
- 查清当前 AGP 版本要求的最低 Gradle 版本（官方文档或
com.android.tools.build:gradle的 release notes） - 更新
gradle-wrapper.properties中的distributionUrl到满足要求的**完整版本号** - 不要指望 Wrapper “自动降级适配”，它只负责下载和启动，不处理 JVM 兼容逻辑
最易被忽略的一点：很多人改完 distributionUrl 就以为完事了，其实 gradle-wrapper.jar 也得同步更新 —— 它是和对应 Gradle 版本绑定的启动器，旧 jar 启动新 Gradle 会直接 NoClassDefFoundError。
