./gradlew 不依赖本地 Gradle 安装，由项目自身通过 gradle-wrapper.properties 指定并自动下载对应版本的 Gradle，确保构建一致性；而 gradle 命令直接调用系统 PATH 中的全局 Gradle，易因版本不匹配或未安装导致构建失败。
用 ./gradlew 而不是 gradle，核心就一条：它不依赖你电脑上装没装 Gradle、装的是哪个版本——项目自己管版本，且只为自己服务。
为什么 gradle 命令经常报错或行为不一致
执行 gradle build 时，系统直接调用你本地 PATH 里的 gradle 可执行文件。这意味着：
- 如果你没装 Gradle，会提示
command not found - 如果你装了但版本是 8.5，而项目实际需要 7.6，可能因 DSL 语法变更、API 移除导致构建失败（比如
compile配置被弃用） - CI 服务器、新同事 clone 代码后，必须手动配环境，否则第一行命令就卡住
./gradlew 怎么做到“自带 Gradle”
它本质是两个脚本 + 一个 JAR 的组合：
-
gradlew（macOS/Linux）或gradlew.bat（Windows）：入口脚本，负责检查、下载、启动 -
gradle/wrapper/gradle-wrapper.jar：真正干活的，含下载逻辑和版本校验代码 -
gradle/wrapper/gradle-wrapper.properties：唯一配置源，关键字段是distributionUrl，例如https\://services.gradle.org/distributions/gradle-8.4-bin.zip
第一次运行 ./gradlew build 时，它会按 distributionUrl 下载对应 ZIP 到 ~/.gradle/wrapper/dists/，解压后调用其中的 gradle 二进制；后续再运行，直接复用本地缓存。
修改 Gradle 版本时，gradle wrapper 命令到底干了什么
执行 gradle wrapper --gradle-version 8.5 并不是“升级当前项目”，而是用你本地安装的 gradle（注意：不是 ./gradlew）去生成一套新 wrapper 文件：
- 覆盖
gradle-wrapper.properties中的distributionUrl - 重新下载
gradle-wrapper.jar（版本可能微调，但通常向后兼容） - 不会动你项目里任何
build.gradle或插件配置——这些得你手动适配
⚠️ 容易踩的坑：如果本地 gradle 是 7.2，却执行 gradle wrapper --gradle-version 8.5，大概率失败，因为旧版 wrapper task 不认识新版参数。正确做法是先确保本地有能驱动该版本 wrapper 的 Gradle，或直接改 gradle-wrapper.properties 手动换 URL。
Android 项目里还多一层：Gradle 版本和 Android Gradle Plugin（AGP）必须匹配
很多人改了 gradle-wrapper.properties 却发现 ./gradlew assembleDebug 报错，根源常在这里：
-
gradle-8.4要求 AGP 最低为8.4.0（见 AGP 兼容表） - AGP 版本写在项目根目录的
build.gradle（旧格式）或settings.gradle（新格式）里，例如id 'com.android.application' version '8.4.0' - 二者不匹配时，错误信息往往藏在堆栈深处，比如
Could not find method android() for arguments或Unsupported method: BaseConfig.getApplicationIdSuffix()
真正麻烦的点不在 wrapper 本身，而在于它把 Gradle 版本钉死了之后，所有配套（尤其是 AGP）都得跟着对齐——这个约束关系，比单纯换 JDK 版本更隐蔽、更难排查。
