Gradle 8.4+ 配置缓存失效的典型现象包括Sync无反应、任务属性设置不生效、tasks.named返回空、afterEvaluate逻辑未执行；根本原因是配置阶段提前终止，高危写法有滥用afterEvaluate、错误使用withType、在buildSrc中绕过DependencyHandler API。
Gradle配置缓存失效的典型现象
你改完 build.gradle 或 settings.gradle，点 Sync 却没反应；或者任务属性（比如 compileJava.options.encoding）看起来被设置了，但实际构建时仍是默认值；又或者 tasks.named("assemble") 在 Kotlin DSL 中返回空，afterEvaluate 里的逻辑压根没执行——这些都不是“同步失败”，而是配置阶段提前终止，缓存被跳过或丢弃了。
Gradle 8.4+ 配置缓存失效的三个高危写法
Gradle 8.4 起强制执行「配置即声明」，任何延迟求值若未通过 Provider 或 Property API 显式建模，都会被截断：
-
project.afterEvaluate { tasks.getByName("compileJava").options.encoding = "UTF-8" }—— 已废弃，8.4+ 默认忽略，不报错也不生效 -
tasks.withType(JavaCompile::class) { options.encoding = "UTF-8" }—— 类型推导失败，返回空集合；必须写成tasks.withType(JavaCompile::class).configureEach { ... } - 在
buildSrc中直接调用project.dependencies.add("implementation", "org.example:lib:1.0")—— 绕过DependencyHandler的声明式 API，触发ConfigurationResolutionException
如何快速定位是配置缓存问题而非网络或语法错误
别急着删 .gradle/caches。先做这三件事：
- 在终端运行
./gradlew --configuration-cache --scan，看是否出现Configuration cache entry not found或Configuration cache is disabled提示 - 打开
gradle.properties，确认没有启用org.gradle.configuration.cache=false（显式关闭会掩盖问题） - 检查 IDEA 的 Gradle 设置：Settings → Build, Execution, Deployment → Gradle → 勾选
Build and run using和Run tests using是否都设为Gradle（而非 IntelliJ IDEA），否则 IDE 会绕过 Gradle 的配置缓存机制
修复后仍失效？重点检查这几个隐藏点
配置缓存对“外部状态”极其敏感，以下地方哪怕只有一处读取了非声明式外部值，整个缓存就作废：
-
System.getenv("HOME")、new Date()、File.exists()等运行时调用 —— 必须改用providers.environmentVariable("HOME")或layout.projectDirectory.file("...") - 自定义插件中用了
this.class.classLoader或反射访问项目对象 —— Gradle 无法序列化类加载器上下文 - 模块间通过
rootProject.ext共享变量并动态修改 ——ext属于可变状态，破坏缓存一致性
最常被忽略的是：Kotlin DSL 中误用 val 声明顶层变量代替 extra 或 convention，导致 Gradle 无法追踪其依赖链。
