java项目应使用gradlew wrapper按项目隔离管理gradle版本，避免全局安装导致的版本冲突和ci环境问题；通过gradle wrapper命令生成wrapper文件，确保distributionurl为完整https地址，ide需配置启用wrapper模式。
Java项目不用手动下载Gradle，也不该用系统级“安装”方式配置——Gradle 的推荐用法是通过 gradlew（Wrapper）按项目隔离管理版本，避免全局污染和版本冲突。
为什么不该用 sdk install gradle 或手动配 GRADLE_HOME
全局安装 Gradle 会导致多个项目被迫共用同一版本，一旦某项目依赖特定 Gradle 版本（比如 gradle-8.4 要求 Java 17+，而老项目还在用 gradle-6.9），就会编译失败或插件不兼容。更常见的是 CI 环境因环境变量缺失直接报 Command 'gradle' not found。
-
gradlew是项目自带的脚本（gradlew和gradlew.bat），会自动下载并缓存对应gradle-wrapper.properties中声明的版本 - 所有团队成员和 CI 服务器只要执行
./gradlew build，就能拿到完全一致的构建环境 - 升级 Gradle 只需改一行：
distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip
如何生成或修复 gradle/wrapper/gradle-wrapper.properties
新建项目时用 gradle init 会自动生成 Wrapper；已有项目若缺失，则运行：
gradle wrapper --gradle-version 8.5
这会在项目根目录创建 gradlew、gradlew.bat 和 gradle/wrapper/ 目录。关键检查点：
立即学习“Java免费学习笔记（深入）”；
-
gradle-wrapper.properties中的distributionUrl必须是完整 HTTPS 地址，不能写成gradle-8.5.zip这种相对路径 - 如果公司内网无法访问
services.gradle.org，可提前下载 zip 包，改用file:///path/to/gradle-8.5-bin.zip - 别把
gradle/wrapper/gradle-wrapper.jar提交到 Git —— 它体积小且可再生，但.jar文件容易被 IDE 误标为“可疑二进制”
IDEA / VS Code 中不识别 gradlew 怎么办
不是 Gradle 配置错了，而是 IDE 没启用 Wrapper 模式：
- IntelliJ IDEA：打开
Settings → Build → Build Tools → Gradle，把Build and run using和Run tests using都设为Gradle Init Script，并勾选Use gradle wrapper task configuration - VS Code +
Extension Pack for Java：确保工作区根目录有gradlew，然后在命令面板（Ctrl+Shift+P）运行Java: Configure Classpath，它会自动探测build.gradle并启用 Wrapper - 常见假象：
gradle build成功但./gradlew build报错，大概率是gradle/wrapper/gradle-wrapper.jar损坏，删掉整个gradle/wrapper/后重跑gradle wrapper
真正麻烦的从来不是“怎么装”，而是不同项目对 gradle-wrapper.properties 的版本锁死策略、CI 中 Wrapper 下载超时的 fallback 处理、以及 gradle.properties 里 org.gradle.jvmargs 和本地 JDK 版本的隐式耦合——这些细节不显眼，但出问题时往往卡住一整天。
