Gradle 环境无需手动安装，应优先使用项目自带的 gradlew wrapper；它按 gradle-wrapper.properties 自动下载指定版本，避免版本冲突，且支持多项目多版本共存。
Gradle 环境不需要手动“搭建”——现代 Java 项目几乎都靠 IDE 或 gradlew 自动拉取对应版本，硬装 gradle 命令行反而容易出版本冲突。
用 gradlew 启动项目比装全局 Gradle 更稳
绝大多数开源项目或 Spring Initializr 生成的工程都自带 gradlew（Unix）或 gradlew.bat（Windows）。它会按 gradle/wrapper/gradle-wrapper.properties 里声明的 distributionUrl 自动下载并缓存指定 Gradle 版本（如 https\://services.gradle.org/distributions/gradle-8.5-bin.zip）。
实操建议：
- 直接运行
./gradlew build（macOS/Linux）或gradlew.bat build（Windows），首次会自动下载、解压、执行 - 无需配置
GRADLE_HOME或修改系统 PATH - 不同项目可共存不同 Gradle 版本，互不干扰
- 若提示
Permission denied，给gradlew加执行权限：chmod +x gradlew
IntelliJ IDEA 中 Gradle 项目识别失败的常见原因
IDEA 有时显示 “Project JDK not configured” 或 “No Gradle version set”，不是 Gradle 没装好，而是项目元数据没刷新或 JDK 绑定错位。
立即学习“Java免费学习笔记（深入）”；
实操建议：
- 打开项目后，右下角出现 “Import project from external model” 提示时，点 Import，选
Gradle，勾选Use Gradle from: Wrapper - 确认
Project SDK指向已安装的 JDK（至少 JDK 17，Gradle 8.x 不支持 JDK 8） - 若已有项目但 Gradle 面板为空，右键
build.gradle→Reload project - 避免手动在
Settings → Build → Gradle里填全局路径——这会绕过 wrapper，导致团队协作时行为不一致
build.gradle 最小可用 Java 编译配置长什么样
新项目常卡在 “编译失败：找不到 main 类” 或 “java.lang.NoClassDefFoundError”，本质是源码目录结构或插件没对齐。
实操建议（以 Gradle 8.5 + Java 17 为例）：
- 必须应用
java插件：plugins { id 'java' } - 确保源码在默认路径：
src/main/java/（否则要显式配置sourceSets.main.java.srcDirs） - 显式声明 Java 版本（Gradle 8+ 默认不推断）：
java { toolchain { languageVersion = JavaLanguageVersion.of(17) } } - 如果跑
main方法，需加application插件并设入口类：application { mainClass = "com.example.Hello" }
为什么 gradle build 成功但 java -jar 报错？
gradle build 默认只打 jar，不含依赖和启动逻辑。直接 java -jar 运行会因缺少第三方类而抛 NoClassDefFoundError。
实操建议：
- 打可执行 fat jar：用
shadow插件（需plugins { id 'com.github.johnrengelman.shadow' version '8.1.1'}）后执行./gradlew shadowJar，产出在build/libs/*.jar - 或改用
application插件：./gradlew installDist，可执行文件在build/install//bin/ - 别信网上“加
archiveClassifier就能直接运行”的说法——那只是重命名，不解决依赖打包问题
真正麻烦的从来不是“怎么装 Gradle”，而是 gradle-wrapper.properties 里的版本号、build.gradle 里插件的兼容性、以及 JDK 和 Gradle 的交叉支持矩阵。这些细节不翻官网文档（https://docs.gradle.org/current/userguide/compatibility.html）很容易踩进静默失败的坑。
