最快最稳的Gradle Wrapper升级方式是直接修改gradle/wrapper/gradle-wrapper.properties中的distributionUrl值，如改为gradle-8.10-bin.zip，并确保反斜杠转义正确；同时需同步升级AGP版本、匹配Java 17+环境。
直接改 gradle-wrapper.properties 最快最稳
Gradle Wrapper 升级本质就是换一个下载地址，不涉及本地安装或环境变量。核心动作只有一条：修改项目中 gradle/wrapper/gradle-wrapper.properties 文件里的 distributionUrl 值。
比如要把当前版本升到 8.10（2026 年主流稳定版），打开该文件，把这一行：
distributionUrl=https\://services.gradle.org/distributions/gradle-7.5-bin.zip
改成：
distributionUrl=https\://services.gradle.org/distributions/gradle-8.10-bin.zip
注意三点：
-
-bin.zip后缀比-all.zip更轻量，日常开发够用；若需离线调试源码或文档，才选-all.zip - URL 中的反斜杠
\是 Java 属性文件转义必需的，不能删 - 别手误写成
https://（少一个反斜杠），否则./gradlew会报Connection refused或空指针异常
./gradlew wrapper --gradle-version 适合批量或 CI 场景
命令行方式本质是让 Gradle 自己重生成 wrapper 脚本，适用于需要脚本化、或团队统一升级的场景。它会覆盖 gradlew、gradlew.bat 和 gradle/wrapper/gradle-wrapper.jar。
执行：
./gradlew wrapper --gradle-version 8.10
完成后检查两件事：
-
gradle-wrapper.properties中的distributionUrl是否已自动更新 -
gradlew脚本头部是否包含新版哈希校验注释（如# GENERATED BY GRADLE WRAPPER后带时间戳）
⚠️ 注意：如果项目里已有自定义的 Wrapper task（比如在 build.gradle 里写了 task wrapper(type: Wrapper) { gradleVersion = '7.4' }），这个命令可能被覆盖或冲突，优先删掉这类手动 task 再运行。
升级后必须同步 Android Gradle Plugin（AGP）版本
Gradle 和 AGP 有严格兼容表，只升 Gradle 不升 AGP，大概率报错 Unsupported Gradle version 或 Could not initialize class org.jetbrains.kotlin.gradle.targets.jvm.KotlinJvmCompilerKt。
查兼容关系最准的方式是看官方文档：Android Gradle Plugin 版本说明。例如：
- Gradle 8.10 → 要求 AGP ≥ 8.4.0
- AGP 8.4.0 的
classpath写法是：com.android.tools.build:gradle:8.4.0 - 对应要改根目录
build.gradle（或build.gradle.kts）里的dependencies块
别漏掉 settings.gradle 里可能存在的 pluginManagement 配置——如果用了预编译脚本插件，这里也得同步更新插件版本。
Java 版本不匹配是静默失败的主因
Gradle 8.x 默认要求 Java 17+，而很多老项目还卡在 Java 11 或 Java 8。现象是：./gradlew -v 报 UnsupportedClassVersionError，或者构建中途卡住无日志。
验证方式：
- 终端运行
java -version，确认输出含17.或更高 - 检查
gradle.properties是否设了org.gradle.java.home，指向旧 JDK 路径 - Android Studio 用户还要进
File → Project Structure → SDK Location，核对Gradle Settings → Gradle JDK是否选对
最容易被忽略的一点：CI 流水线（如 GitHub Actions、GitLab CI）里常硬编码了 Java 版本，光本地改没用。得同步更新 workflow 文件中的 java-version。
