Java Gradle configuration cache 不生效怎么办

我排查 Java 构建的 Gradle configuration cache 时，会先记录两次 help 的基线：第一次是否写入缓存，第二次是否出现复用提示。若一直没有复用，我不会先把 problems=warn 写进全局配置，而是先区分缓存没有启用，还是构建逻辑在配置阶段/任务执行阶段引用了不能被重新加载的状态。最小排查顺序是用 Wrapper 执行 help，看问题报告，再把环境输入改成 Provider 或任务属性。

官方文档：https://docs.gradle.org/current/userguide/configuration_cache.html

先看懂 configuration cache 的两个边界

configuration cache 保存的是已经计算出的任务图和所需状态，让下一次相同构建可以跳过大部分配置阶段。它不是普通的任务输出缓存，也不是“打开后所有插件自动兼容”的开关。Gradle 文档当前仍把它列为默认关闭能力，命令行可以用 --configuration-cache 按次开启。

因此一次成功不等于已经生效：第一次通常会出现“没有可用缓存，正在计算任务图”，随后写入缓存；第二次在输入没有变化时才应看到复用提示。如果第一次就出现问题，优先看 settings、build script、插件 apply 逻辑；如果 help 能写入而真实任务失败，问题更可能在具体任务实现。

先用 help 把问题缩到配置阶段

在项目根目录连续运行两次下面的命令。这里的重点不是跑完整构建，而是让 Gradle 用最小任务检查构建逻辑。

# 第一次检查配置阶段，并允许 Gradle 写入配置缓存
./gradlew help --configuration-cache

# 第二次使用完全相同的任务，观察是否出现复用提示
./gradlew help --configuration-cache

如果第二次仍然没有复用，先确认两次命令的参数、项目目录和重要配置输入没有变化。若输出给出 configuration cache report，打开报告中的问题条目；它会按消息或任务聚合，并链接到对应的兼容要求。

排障期间可以临时使用下面的警告模式来收集更多问题，但它不是修复方案：

# 只用于迁移排查，避免把警告模式当成长期配置
./gradlew help --configuration-cache --configuration-cache-problems=warn

警告模式可能让带问题的缓存被保存，命中后任务拿到不完整或不正确的状态。确认根因后，应恢复默认的失败策略，而不是把问题藏起来。

把配置阶段读取改成可序列化的任务输入

最常见的障碍是任务动作里继续使用 Project、Gradle 或其他实时模型对象，或者在配置阶段通过任意外部进程读取值。改造目标不是“少写几行”，而是让任务只接收可以保存、重新加载的输入。

import org.gradle.api.DefaultTask
import org.gradle.api.provider.Property
import org.gradle.api.tasks.Input
import org.gradle.api.tasks.TaskAction

abstract class BuildInfoTask : DefaultTask() {
    @get:Input
    abstract val buildNumber: Property

    @TaskAction
    fun printBuildInfo() {
        // 任务执行时只读取已经声明的属性，不再访问 Project 或 Gradle 实时模型。
        logger.lifecycle("构建编号：${buildNumber.get()}")
    }
}

tasks.register("buildInfo") {
    // Provider 让环境变量成为可追踪的输入，默认值覆盖本地没有 CI 编号的情况。
    buildNumber.convention(
        providers.environmentVariable("BUILD_NUMBER").orElse("local")
    )
}

上面的关键是三件事：属性用 @Input 声明；环境变量通过 Provider 接入；@TaskAction 不捕获 Project。类似地，文件、系统属性和外部信息也应通过 Gradle 能追踪的 Provider、任务输入或注入服务表达。

第三方插件暂时改不了时，只隔离一个任务

有些遗留任务确实依赖执行阶段的 Project，或来自尚未完成迁移的第三方插件。这时可以把它明确标记为不兼容，让包含它的构建不保存错误的缓存，同时不影响其他任务继续采用 configuration cache。

tasks.named("legacyReport") {
    // 记录原因，避免局部退出变成永久遗留配置。
    notCompatibleWithConfigurationCache("执行阶段仍读取 Project，等待插件迁移")
}

这不是把问题改成警告，而是明确告诉 Gradle：这个任务暂时不参加缓存。若它是常用任务，仍应跟踪插件升级、拆出独立任务输入，或把构建逻辑重构成可注入的服务。

常见问题

为什么第一次运行没有复用提示？

第一次通常是 cache miss，需要先计算并保存任务图；应保持参数不变再运行第二次。

把 org.gradle.configuration-cache.problems=warn 固定下来可以吗？

不建议。它适合短期收集问题，长期使用可能让缓存带着不完整状态被复用。

为什么 IDE 同步没有明显收益？

Gradle 文档把 IDE sync 与通过 IDE 执行任务区分开；配置缓存主要优化任务执行流程，不应把同步表现直接当成任务缓存是否生效的结论。

我的判断标准很简单：两次 help 的输出先建立可重复基线，报告再决定改配置输入还是隔离任务。这样既能保留 configuration cache 的复用收益，也不会用全局警告掩盖仍然不兼容的 Java 构建逻辑；如果真实构建仍有问题，就把同一组输入带到目标任务继续复查。