Gradle运行时版本与Android Gradle Plugin（AGP）版本必须严格匹配，否则构建失败；需同步修改gradle-wrapper.properties中的distributionUrl（如gradle-8.7-bin.zip）和build.gradle中AGP的classpath或id版本（如8.1.2），并确保Java版本、插件仓库及SDK配置兼容。
直接改两个地方：gradle-wrapper.properties 里的 Gradle 运行时版本，和 build.gradle 里的 Android Gradle Plugin（AGP）版本。两者必须匹配，不匹配会报错或构建失败。
修改 gradle-wrapper.properties 中的 Gradle 运行时版本
这个文件控制的是底层 Gradle 引擎本身（比如 gradle-8.7-bin.zip），不是插件。路径固定为 gradle/wrapper/gradle-wrapper.properties。
- 打开后找到
distributionUrl行，例如：distributionUrl=https\://services.gradle.org/distributions/gradle-7.5-bin.zip - 把版本号换成你想要的，比如升级到
8.7就改成：distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip - 注意后缀：
-bin.zip（轻量版，推荐）或-all.zip（含源码和文档，体积大但调试方便） - 如果官网下载慢或失败，可换国内镜像，例如腾讯云：
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip
同步修改 build.gradle 中的 AGP 版本
AGP（com.android.tools.build:gradle）是 Android 官方提供的 Gradle 插件，它和 Gradle 运行时版本有严格兼容关系。不能只改一个。
- 在项目根目录的
build.gradle（或build.gradle.kts）中，找到dependencies块下的classpath声明 - 旧写法（Groovy）：
classpath 'com.android.tools.build:gradle:7.4.2' - 新写法（Kotlin DSL）：
id("com.android.application") version "8.1.2" apply false（AGP 8.0+ 推荐用这种方式） - 务必查官方兼容表（如 Android Gradle Plugin 版本说明），例如 AGP 8.1.2 要求 Gradle 8.0–8.2，填 8.7 就不合法
常见报错和踩坑点
改完不 sync 或只改一半，大概率立刻出错。最典型的几个现象：
-
Could not find method android() for arguments [...] on project ':app' of type org.gradle.api.Project.→ AGP 没正确加载，通常是build.gradle里 classpath 版本太低或拼写错误 -
Unsupported Java. Your build is currently configured to use Java 17 and Gradle 6.7.1.→ Gradle 运行时版本太老，不支持当前 JDK，得升gradle-wrapper.properties -
Plugin [id: 'com.android.application', version: '8.1.2'] was not found in any of the following sources:→ 用了新 AGP 但没在settings.gradle或build.gradle里声明插件仓库（必须含mavenCentral()和google()） - Sync 成功但编译报
Cannot resolve symbol R→ 往往是 AGP 升级后，compileSdkVersion、targetSdkVersion或依赖库（如androidx）也需要一并更新
验证和收尾动作
改完两处、sync 完成后，别急着写代码，先做三件事：
- 终端执行：
./gradlew --version确认输出的 Gradle 版本和gradle-wrapper.properties一致 - 在 Android Studio 的 File > Project Structure > Project 页面，检查
Android Gradle Plugin Version和Gradle Version是否与你手动设置的完全对应 - 运行
./gradlew app:assembleDebug看是否能干净打出 APK；如果有警告（如Deprecated Gradle features were used），说明某些 DSL 写法已过时，需按提示迁移（比如把compile改成implementation）
最容易被忽略的是 AGP 和 Gradle 运行时之间的版本锁死关系——它们不是独立升级的模块，而是一对绑定组件。选错组合，sync 都过不去，更别说编译了。
