应优先使用 gradle wrapper 而非系统包管理器安装的 gradle，因其版本过时、缺失源码文档、绕过 wrapper 机制导致构建不可复现；正确做法是删除系统 gradle 命令，始终用 ./gradlew 并确保 gradle-wrapper.properties 与 jar 版本一致。
别用系统包管理器装 Gradle —— 它几乎总是过时的，且无法与项目所需的 gradle-wrapper.properties 版本对齐，尤其在 Android 或多 JDK 环境下会直接导致 Sync 失败、Could not determine java version、Unsupported major.minor version 等错误。
为什么系统包管理器的 Gradle 不能用
Linux 发行版（如 Ubuntu 的 apt、macOS 的 brew install gradle）打包的 Gradle 是“发行版维护者认为稳定”的版本，不是“你项目需要的版本”。它通常滞后 2–4 个大版本，且不带 -all.zip 中的 src/ 和 docs/，Android Studio 无法跳转 DSL 源码、高亮失效、gradle-wrapper.jar 版本不匹配。更关键的是：它绕过了 Gradle Wrapper 机制，使 ./gradlew 失去控制权，项目构建行为不可复现。
正确做法：优先用 Gradle Wrapper，禁用系统 gradle 命令
Gradle Wrapper 是项目级的构建入口，它由 gradle/wrapper/gradle-wrapper.properties 控制，内容类似：
distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip
这意味着项目明确要求使用 8.5 版本，跟系统里装的 gradle 命令完全无关。你应该：
- 删掉或重命名系统安装的
gradle命令（比如sudo mv /usr/bin/gradle /usr/bin/gradle-system-bak），避免误触发 - 始终用
./gradlew build、./gradlew --version启动构建 - 如果 IDE（如 Android Studio）提示 “Use default gradle wrapper”，务必勾选，而不是选 “Use gradle from PATH”
- 检查
gradle-wrapper.jar是否与distributionUrl匹配：它的版本号必须和 URL 中的版本一致，否则会静默降级或报错
需要手动安装时，只解压 -all.zip 到本地目录，不设全局环境变量
某些 CI 场景或离线环境确实要本地部署 Gradle，这时必须用 -all.zip（如 gradle-8.5-all.zip），解压后直接指向该路径，而非依赖 GRADLE_HOME：
- 解压到固定位置，例如
~/gradle/gradle-8.5 - 在 Android Studio 的
Settings > Build > Build Tools > Gradle中，选择 “Gradle user home” 下的 “Use gradle from path”，填入~/gradle/gradle-8.5 - 不要设置
GRADLE_HOME或修改PATH—— 这会污染其他项目，尤其当你同时维护 JDK 8 + Gradle 6.9 和 JDK 17 + Gradle 8.5 的项目时 - 验证方式：在项目根目录运行
./gradlew --version，输出中的 Gradle version 必须与distributionUrl一致，JVM version 应匹配项目toolchain要求
真正麻烦的从来不是“怎么装新版本”，而是“如何让每个项目只用它自己声明的版本”，Wrapper 就是为此存在。一旦你开始靠 sudo apt upgrade gradle 解决问题，就等于主动放弃了构建可复现性这个底线。
