Java项目集成Gradle需确保Gradle Wrapper配置、build.gradle结构与JDK版本三者对齐；必须声明Java工具链、依赖仓库和测试配置，常见失败源于JDK不兼容、仓库配置错误或JDK 11+模块缺失。
Java项目集成Gradle不是“装个插件就完事”，关键在于让gradle命令能被项目正确识别、依赖能正常解析、构建产物符合预期——这取决于gradle-wrapper配置、build.gradle结构和JDK版本对齐。
确认本地是否真需要手动安装Gradle
绝大多数现代Java项目应使用Gradle Wrapper（gradlew），而非全局安装gradle命令。手动安装容易引发版本冲突，尤其当团队协作或CI环境不一致时。
-
gradlew脚本会自动下载并缓存指定版本的Gradle（路径在gradle/wrapper/gradle-wrapper.properties中） - 检查项目根目录是否存在
gradlew（Linux/macOS）或gradlew.bat（Windows） - 若不存在，不要运行
gradle init——那是新建空项目用的；应从已有项目拉取，或由维护者提供正确的wrapper
build.gradle里必须声明的三要素
一个可构建的Java项目，build.gradle至少要明确：语言版本、源码位置、依赖仓库。缺一不可，否则./gradlew build会失败或编译出错。
- 用
java { toolchain { languageVersion = JavaLanguageVersion.of(17) } }声明目标JDK，比sourceCompatibility更可靠（尤其在多JDK共存时） -
repositories必须包含至少一个可用仓库，例如mavenCentral()；若公司用Nexus/Artifactory，需配maven { url "https://nexus.example.com/repository/maven-public/" } -
dependencies中，测试依赖如testImplementation 'org.junit.jupiter:junit-jupiter:5.10.0'必须与test { useJUnitPlatform() }配合，否则测试不执行
常见构建失败的三个典型原因
运行./gradlew build报错，90%集中在以下三类，优先排查：
-
“Could not determine java version from 'XX.XX.X’”：说明
JAVA_HOME指向了JRE或不兼容的JDK（如JDK 21用于要求JDK 11的Gradle版本）。查gradle/wrapper/gradle-wrapper.properties中的distributionUrl，再对照Gradle JDK兼容矩阵 -
“Could not resolve all files for configuration ':compileClasspath'”：不是网络问题，先看
build.gradle里repositories是否拼错URL，或是否漏了mavenLocal()但本地没发布过依赖 -
“package javax.annotation does not exist”（JDK 11+）：这是模块移除导致的，需加
compileOnly 'javax.annotation:javax.annotation-api:1.3.2'，而非试图降级JDK
IDE里Gradle同步失败怎么办
IntelliJ或Eclipse显示“Cannot resolve symbol”或同步卡住，通常不是IDE问题，而是Gradle本身未完成初始化。
- 先在终端运行
./gradlew --version，确认wrapper能启动且输出Gradle和JDK版本 - 删掉项目下的
.gradle/和build/目录（不影响源码），再重试同步——缓存损坏很常见 - IDE设置里关闭“Use default gradle wrapper”以外的选项，尤其别勾选“Use local gradle distribution”，那会绕过
gradle-wrapper.properties
Gradle集成最易被忽略的点是：wrapper版本、JDK版本、build.gradle语法版本三者必须形成闭环。比如用Gradle 8.4写plugins { id 'java' version '1.9' }会直接报错——因为8.4只支持plugin DSL到1.8。这种细节不会报“版本不匹配”，只会抛模糊的Could not find method plugins()。
