gradle-wrapper.properties是Gradle Wrapper升级时唯一必须手动修改的文件，位于gradle/wrapper/目录下，核心是更新distributionUrl字段指向新版本包（如gradle-8.0-all.zip）；同时需清理~/.gradle/wrapper/dists/缓存并确保gradle-wrapper.jar同步更新，否则易触发兼容性错误。
gradle-wrapper.properties 文件必须更新
这是唯一一个 Gradle Wrapper 升级时必须手动修改的文件。它位于 gradle/wrapper/gradle-wrapper.properties，核心是 distributionUrl 字段。升级后该 URL 必须指向新版本的二进制包，例如从 gradle-7.5-bin.zip 改为 gradle-8.0-all.zip。注意：-all 后缀在 AGP 8.0+ 中更稳妥，避免因缺失源码或文档导致 IDE 插件解析失败。
gradlew 和 gradlew.bat 的哈希值会变（但通常不用改）
这两个脚本本身是自动生成的启动器，内容不随 Gradle 版本号显式变化，但其内部校验逻辑和打包行为依赖于 gradle-wrapper.properties。当你运行 ./gradlew wrapper --gradle-version 8.0 时，它们会被重写——尤其是 gradlew.bat 中的 DEFAULT_JVM_OPTS 和启动参数可能调整。如果你手动替换了 gradle-wrapper.properties 却没刷新脚本，可能出现 Could not determine java version from '17.0.1' 或 Unsupported class file major version 这类错误。
根目录下的 gradle/ 目录一般不变，但内容可能被覆盖
gradle/ 目录下除 wrapper/ 外的子目录（如 libs/、init.d/）与 Wrapper 升级无关，不会被自动修改。但要注意：gradle/wrapper/ 下的 gradle-wrapper.jar 一定会更新——它是真正负责下载和缓存 Gradle 发行版的代理组件。旧版 gradle-wrapper.jar 可能无法识别 8.0+ 的发行版结构，导致 Connection refused 或 404 on distribution URL。
build.gradle 和 settings.gradle 不直接受影响，但可能触发兼容性问题
这些文件本身不需要因 Wrapper 升级而改动，但实际中常伴随 AGP 升级一起操作。比如：build.gradle 中的 plugins { id 'com.android.application' version '8.1.0' } 必须与 Wrapper 的 Gradle 版本匹配（AGP 8.1 要求 Gradle 8.0+）。若只升 Wrapper 不升 AGP，或反之，大概率遇到 Minimum supported Gradle version is X.X.X. Current version is Y.Y.Y 错误。另外，Gradle 8.0+ 默认启用 --configuration-cache 兼容性检查，可能暴露原本被忽略的 buildSrc 或 init script 中的动态配置问题。
最容易被忽略的是：本地 ~/.gradle/wrapper/dists/ 缓存不会自动清理。即使改了 distributionUrl，Gradle 仍可能复用旧版解压目录，导致静默行为异常（比如编译输出路径错乱、Kotlin 插件版本冲突）。建议升级后执行 ./gradlew --stop && rm -rf ~/.gradle/wrapper/dists/gradle-* 再重试。
