应优先使用项目自带的gradlew（或gradlew.bat）启动构建，它会自动下载并调用gradle-wrapper.properties指定的Gradle版本；直接调用系统全局gradle易导致版本冲突或命令未找到。
直接用 gradlew 启动，别碰系统全局 gradle
绝大多数“构建失败”其实卡在第一步：你本地装了 Gradle，但项目根本没打算用它。Gradle 项目靠 gradlew（Linux/macOS）或 gradlew.bat（Windows）驱动，它会自动下载、缓存并调用 gradle/wrapper/gradle-wrapper.properties 里声明的版本。运行 gradle build 报 “command not found” 或版本冲突，基本就是误用了全局命令。
正确做法只有一条：进项目根目录，直接执行 ./gradlew build（或 gradlew.bat build）。首次运行会自动拉取对应版本到 ~/.gradle/wrapper/dists/，后续就快了。
build.gradle 缺 java 插件会导致编译任务不存在
如果执行 ./gradlew compileJava 报错 “Task ‘compileJava’ not found”，说明 build.gradle 没启用 Java 插件。哪怕源码就在 src/main/java 下，没有插件，Gradle 就当它不存在。
- 必须显式声明：
plugins { id 'java' } - 确认源码路径符合约定：
src/main/java/放主代码，src/test/java/放测试，否则插件不会扫描 - 若源码在非标准路径（比如
src/下直接是.java），得手动重配：sourceSets.main.java.srcDirs = ['src']
主类找不到？application 插件和 mainClass 都得配
./gradlew run 失败，常见错误是 No main class specified 或 Could not find or load main class。这两个问题根源不同：
立即学习“Java免费学习笔记（深入）”；
-
No main class specified：没加application插件，或没在application块里写mainClass -
Could not find or load main class：类名写错了（必须带完整包路径，如com.example.Main），或src/main/java/com/example/Main.java文件本身不存在 / 拼写不一致
配置示例：
plugins {
id 'java'
id 'application'
}
application {
mainClass = 'com.example.HelloWorld'
}
JDK 版本不匹配会静默失败或编译报错
尤其是 JDK 17+ 项目，不显式声明 toolchain，javac 可能用错版本，导致 record、sealed 等语法编译失败，或测试跑不起来。
在 build.gradle 里加：
java {
toolchain {
languageVersion = JavaLanguageVersion.of(17)
}
}
另外注意：JUnit 5 必须配 testImplementation 'org.junit.jupiter:junit-jupiter' + test { useJUnitPlatform() }，否则 ./gradlew test 什么也不跑。
最常被忽略的是：多模块项目中，settings.gradle 必须用 include 'module-a', 'module-b' 显式声明子模块，否则子模块的 build.gradle 根本不加载 —— 这个坑在迁移老 Maven 项目时特别隐蔽。
