Gradle Wrapper 是项目级构建入口，通过 gradlew 脚本、gradle-wrapper.jar 和 gradle-wrapper.properties 确保团队和 CI 使用完全一致的 Gradle 版本，避免本地 Gradle 导致的版本不一致与构建失败。
Gradle Wrapper 是什么，为什么不该直接装本地 Gradle
Wrapper 不是可选插件，而是 Java 项目事实上的构建入口。它把 gradlew 脚本、gradle/wrapper/gradle-wrapper.jar 和 gradle/wrapper/gradle-wrapper.properties 打包进项目，确保所有开发者和 CI 使用**完全一致的 Gradle 版本**。
直接用本地 gradle 命令（比如通过 SDKMAN 或手动解压安装）会绕过 Wrapper，导致：不同人执行 ./gradlew build 和 gradle build 结果不一致；CI 环境没装对应版本就直接失败；升级 Gradle 时漏改本地配置，团队成员各自为政。
- Wrapper 是项目级的，本地 Gradle 是机器级的 —— 二者定位完全不同
- CI/CD 流水线（如 GitHub Actions、GitLab CI）默认只认
./gradlew，不预装任何 Gradle -
gradle wrapper --version这种命令根本不存在；Wrapper 版本由gradle-wrapper.properties中的distributionUrl决定
如何生成或更新 gradle-wrapper.properties 中的 distributionUrl
关键不是“下载哪个包”，而是让 distributionUrl 指向一个可用、稳定、与项目兼容的二进制分发地址。这个 URL 必须匹配 Gradle 官方发布的结构：https://services.gradle.org/distributions/gradle-8.5-bin.zip（注意结尾是 -bin.zip，不是 -all.zip 或 -src.zip）。
常见错误现象：Could not find or load main class org.gradle.wrapper.GradleWrapperMain，基本就是 gradle-wrapper.jar 和 distributionUrl 版本不匹配，或者 URL 被手动改错（比如多加了空格、用了 http 而非 https、路径拼写错误）。
立即学习“Java免费学习笔记（深入）”；
- 推荐做法：用
gradle wrapper --gradle-version 8.5自动生成（前提是本机已装有能运行该命令的 Gradle，建议用 8.0+） - 手动修改时，只改
gradle/wrapper/gradle-wrapper.properties里的distributionUrl行，其他字段（如distributionBase）保持默认即可 - Java 17+ 项目慎用 Gradle build.gradle.kts）在 Gradle 7.6+ 更稳定
- 国内访问慢？可临时替换为清华镜像：
https://mirrors.tuna.tsinghua.edu.cn/gradle/gradle-8.5-bin.zip，但需确认镜像同步及时且校验通过
本地 Gradle 安装其实只用于开发调试，不是必须项
你不需要为每个项目配一套本地 Gradle。真正需要本地安装的场景极少：比如要调试 Gradle 插件源码、想快速试跑某个自定义 task 而不想等 Wrapper 下载、或离线环境无法拉取远程 distribution。
如果真要装，别用 brew/macports/apt 直接装（版本不可控、路径难管理），优先用版本管理工具：
- SDKMAN：运行
sdk install gradle 8.5，再sdk use gradle 8.5切换，干净隔离 - 手动解压后，把
bin/加入$PATH，但务必确认which gradle指向你想要的路径，避免和旧版本冲突 - 验证方式不是
gradle -v，而是gradle --version（前者可能被 alias 干扰） - 删掉本地 Gradle 不影响
./gradlew运行 —— Wrapper 会自己下载所需版本到~/.gradle/wrapper/dists/
IDE（IntelliJ IDEA / VS Code）里 Gradle 同步失败的典型原因
IDE 显示 “Cannot resolve symbol ‘org.gradle’” 或 “No projects found”，往往不是 Gradle 配置错，而是 IDE 没正确识别 Wrapper 或 Java 环境不匹配。
IntelliJ 默认会自动检测 gradlew，但容易卡在“选择 Gradle JVM”这一步：它可能默认用了项目 JDK，而 Wrapper 下载的 Gradle 运行时需要更高版本（比如 Gradle 8.5 要求 Java 17+）。这时候强行点 OK 就会同步失败。
- 解决方法：打开
Settings > Build > Build Tools > Gradle，把Gradle JVM改成一个明确的、满足要求的 JDK（如17.0.1），不要选Project SDK自动推断 - VS Code 用户需确保已安装
Gradle for Java扩展，并在工作区设置中指定"java.configuration.updateBuildConfiguration": "interactive" - 删除
.idea/或.vscode/后重新导入项目，比反复点击 “Reload project” 更可靠 - 如果
./gradlew tasks在终端能跑通，但 IDE 同步失败，基本可以排除build.gradle本身问题
Wrapper 的核心逻辑很简单：第一次运行 ./gradlew 时，它检查本地有没有对应版本的解压目录；没有就从 distributionUrl 下载、校验、解压，再启动。整个过程对用户透明，但一旦 gradle-wrapper.jar 损坏、properties 文件编码异常（比如含 BOM）、或网络策略拦截了 services.gradle.org，就会卡在最开始那一步，而且错误提示极其模糊。
