gradle与java版本必须严格匹配：java 17需gradle 7.6+，java 21需gradle 8.4+；版本错配会导致“unsupported class file major version”或编译失败，应通过toolchain配置jdk而非硬编码sourcecompatibility。
Gradle版本和Java版本必须对齐
Java 17项目用Gradle 6.x会直接报Unsupported class file major version 61，因为Gradle 6.9最大只支持到Java 15。反过来，Java 8项目用Gradle 8.x虽然能跑，但sourceCompatibility默认变成17，编译直接失败。
- 查清当前JDK版本：
java -version，再查Gradle兼容表（官方文档里叫“Compatibility Matrix”） - 推荐组合：Java 17 → Gradle 7.6+；Java 21 → Gradle 8.4+
- 在
gradle/wrapper/gradle-wrapper.properties里改distributionUrl，别只改build.gradle里的插件版本
build.gradle里不要硬写sourceCompatibility=17
很多人复制粘贴时把sourceCompatibility = 17写死在build.gradle，结果CI环境用Java 11跑就爆红——Gradle会按这个值去调javac，但没检查JVM实际版本。
- 更稳的做法是用
java { toolchain { languageVersion = JavaLanguageVersion.of(17) } }（Gradle 17+） - 旧版Gradle（sourceCompatibility = JavaVersion.VERSION_17，它比字符串更安全
- 如果项目要多JDK兼容（比如同时支持11和17），别设全局
sourceCompatibility，改用compileJava.options.release = 11
依赖冲突时，dependencyInsight比exclude更准
exclude group: 'org.slf4j'看似解了冲突，实则可能砍掉某个模块真正需要的桥接器，导致运行时报NoClassDefFoundError: org/slf4j/spi/LoggerFactoryBinder。
- 先定位冲突来源：
./gradlew dependencies --configuration runtimeClasspath | grep slf4j - 再精准分析：
./gradlew dependencyInsight --dependency slf4j-api --configuration runtimeClasspath - 根据输出里“selected by rule”那行，决定是
force统一版本，还是只exclude某一层的传递依赖
settings.gradle里include路径错一位，整个IDE都识别不了模块
新建子模块后，IntelliJ显示“unlinked Gradle project”，或者./gradlew build提示Project with path ':common' could not be found，八成是settings.gradle里include ':common'对应的实际目录名其实是commons或common-utils。
立即学习“Java免费学习笔记（深入）”；
- 确认路径是否大小写敏感（macOS/Linux下
Common≠common） - 子模块根目录下必须有
build.gradle或build.gradle.kts，空文件夹不会被识别 - 改完
settings.gradle后，别忘了在IDE里点“Reload project”，命令行也要重新运行./gradlew --refresh-dependencies
Gradle配置里最麻烦的不是语法，而是那些隐式生效的约定——比如src/main/java路径、group默认值、甚至test任务自动绑定Test类型。一旦某个地方偏离约定又没显式声明，问题就藏得深，还容易误判为IDE缓存问题。
