执行 ./gradlew wrapper 默认只更新脚本不修改 gradle-wrapper.properties，必须加 --gradle-version 8.10 才能更新 distributionUrl；还需手动清理 ~/.gradle/wrapper/dists/ 缓存并同步 AGP、JDK 版本以确保构建真正生效。
执行 ./gradlew wrapper 第一遍只更新脚本，不更新配置文件
很多人以为运行一次 ./gradlew wrapper 就能完成整个 Wrapper 升级，结果发现 gradle-wrapper.properties 里的 distributionUrl 没变，或者新版本的 gradlew 脚本仍指向旧版 Gradle。这是因为 Gradle 自带的 wrapper 任务默认只生成或刷新脚本（gradlew、gradlew.bat 和 gradle-wrapper.jar），但不会自动改写 gradle-wrapper.properties 中的版本地址——它只会保留你当前已有的配置项，除非你显式指定参数。
常见错误现象：
– 执行 ./gradlew wrapper 后，gradle-wrapper.properties 里仍是 gradle-7.5-bin.zip，而你本意是升到 8.10
– 下次运行 ./gradlew build 依然拉取旧版本，构建失败或插件不兼容
解决方法是加参数强制指定目标版本：
-
./gradlew wrapper --gradle-version 8.10—— 这才真正触发distributionUrl更新 -
./gradlew wrapper --distribution-type all—— 如果需要源码+文档包（比如调试 Gradle 本身） - 必须搭配使用，单独跑
./gradlew wrapper不带参数等于白跑
gradle-wrapper.properties 被 Git 忽略或权限锁定导致写入失败
即使加了 --gradle-version，第二遍执行仍可能“看似成功却没生效”。典型原因是：gradle-wrapper.properties 文件被 IDE 锁定、被 Git 标记为只读、或所在目录无写入权限（尤其在 Windows WSL 或某些 CI 容器中）。
容易踩的坑：
- IDE（如 Android Studio）正在后台扫描项目，会独占该文件，导致
wrapper任务静默跳过写入 -
git update-index --chmod=+x gradlew执行后忘了同步gradle-wrapper.properties的权限，某些 Linux 环境下属性文件写入失败不报错 - CI 流水线用的是缓存的
~/.gradle/wrapper，但本地gradle-wrapper.properties已改，实际运行时仍加载旧缓存
验证是否真的写入成功：直接打开 gradle/wrapper/gradle-wrapper.properties，检查 distributionUrl 是否变成你指定的 URL，且末尾 ZIP 名称匹配（例如 gradle-8.10-all.zip）。
升级后首次运行 ./gradlew 仍卡在旧版本下载
这是最迷惑人的现象：明明 gradle-wrapper.properties 已更新，但执行 ./gradlew build 时控制台还是显示 “Downloading gradle-7.5-bin.zip”。原因在于 Gradle Wrapper 的缓存机制——它优先检查 GRADLE_USER_HOME/wrapper/dists/ 下是否存在对应解压目录（如 gradle-7.5-bin/xxx），如果存在，就直接复用，哪怕配置文件已改成 8.10。
这不是 bug，是设计使然：避免重复下载。但对升级来说，它掩盖了真实状态。
正确做法是：
- 删掉本地缓存中旧版本的完整目录：
rm -rf ~/.gradle/wrapper/dists/gradle-7.5-bin/ - 或者加
--no-daemon强制绕过 Daemon 缓存：./gradlew --no-daemon build - CI 环境建议加
--refresh-dependencies配合清理，否则可能复用旧 Daemon 进程导致静默降级
AGP 与 Gradle 版本强耦合，单升 Wrapper 不够
Android 项目里，只升级 Wrapper 很容易掉进“版本错配”陷阱。Gradle 8.x 要求 AGP 8.4+，而 AGP 8.4 又要求 JDK 17+。如果你只改了 gradle-wrapper.properties，但没同步更新根项目的 build.gradle[.kts] 里的 com.android.tools.build:gradle 版本，或者没调高 compileSdk 和 targetSdk，./gradlew build 会在 Configuration 阶段直接失败，报错类似：Unsupported version of Android Gradle Plugin: 8.2.0. Minimum supported version is 8.4.0.
所以所谓“执行两遍”，本质是：第一遍确保 Wrapper 脚本和配置落地；第二遍才是真正验证构建流程能否跑通——而这依赖于 AGP、JDK、Kotlin 插件三者全部对齐。
最容易被忽略的一点：Android Studio 的内置 Gradle 版本提示（右下角弹窗）只反映 IDE 自身偏好，和项目实际使用的 gradlew 无关。别信那个弹窗，只信 gradle-wrapper.properties 和终端输出的 downloading 日志。
