如何提升Java/Spring Boot多模块项目Gradle构建缓存的有效性？

你的假设没有问题 #

无代码修改的连续构建中，绝大多数可缓存任务应该命中缓存。Gradle默认对编译、测试、打包等核心任务支持缓存，你的情况说明存在任务不可缓存、输入输出未正确声明或缓存配置异常的问题。

排查步骤 #

1. 定位未命中缓存的任务及原因 #

执行构建时添加--info参数，查看详细日志：

./gradlew build --build-cache --info

日志会明确标注每个任务未命中缓存的原因，常见场景包括：

• Task has not declared any outputs despite executing actions：任务未声明输出，无法生成缓存
• Input property 'xxx' has changed value：某个输入属性发生了未预期的变化
• Cache entry not found：首次构建后二次构建才会生成缓存，此提示仅在第一次构建后第二次执行时出现属正常情况

2. 检查任务的可缓存性 #

• 通过./gradlew tasks --all查看任务的Cacheable标记，未标记的任务不会参与缓存
• 自定义任务需添加@CacheableTask注解，同时正确声明输入（@Input、@InputFile等）和输出（@OutputFile、@OutputDirectory等），否则Gradle无法跟踪其状态变化

3. 验证输入输出的稳定性 #

• 动态输入问题：避免任务依赖当前时间、随机数等动态值，若必须使用需标记为@Input；禁止在构建脚本中使用未声明的环境变量/系统属性作为任务输入
• 路径问题：任务输入文件尽量使用相对路径，或通过project.layout获取路径，避免绝对路径导致不同环境下输入哈希变化
• 未声明的输入输出：检查自定义任务是否读取了未标记为输入的文件，或生成了未标记为输出的文件，这类情况会导致Gradle无法正确计算缓存哈希

4. 排查Spring Boot相关任务 #

Spring Boot的bootJar/bootWar默认可缓存，但以下情况会导致失效：

• 配置了动态的mainClassName或未声明的自定义属性
• 打包时包含动态生成的资源（如构建时间戳），需将动态值标记为@Input，或在processResources任务中固定此类值

5. 确认缓存配置正确性 #

• 检查settings.gradle中构建缓存是否正确启用：

  buildCache {
      local {
          enabled = true
      }
      // 若使用远程缓存，需确保地址、权限配置正常
      // remote(HttpBuildCache) {
      //     url = uri("https://your-cache-server")
      // }
  }
  

• 排查是否有任务被强制禁用缓存：部分插件或自定义脚本可能设置outputs.cacheIf { false }，导致任务不参与缓存

6. 检查模块间依赖传递 #

若某模块任务未命中缓存，可能是上游依赖模块的任务输入发生变化。通过./gradlew dependencies梳理依赖关系，确认上游模块是否存在未稳定的输入项

7. 单模块测试缓存有效性 #

单独构建某个模块缩小排查范围：

./gradlew :module-1:build --build-cache

重复执行后若单模块缓存正常，说明问题可能出在跨模块依赖或根项目配置上

内容的提问来源于stack exchange，提问作者Matthias