Gradle复合构建中Build Cache异常问题排查求助

听起来你遇到的是典型的跨环境构建缓存一致性问题，而且只出现在app项目上，说明问题大概率和app项目的任务配置、缓存键计算，或者GitLab流水线的并行任务调度有关。结合我处理类似问题的经验，给你几个排查方向：

1. 并行任务的依赖声明不完整，导致缓存竞态 #

GitLab流水线里并行执行junit-mocks和junit-app，但后续集成测试依赖的是app:jar和mocks:jar任务。如果这两个JUnit任务和Jar任务之间的依赖关系没在Gradle里明确声明，就可能出现缓存写入/读取的竞态条件：

• 比如junit-app任务可能触发了clean或者修改了build/classes目录，但Gradle没感知到这个修改会影响jar任务的缓存键；
• 或者并行任务同时写入缓存，导致app的Jar缓存被不完整的中间状态覆盖。

解决/排查： #

• 确保integration-tests项目的集成测试任务明确依赖app和mocks的Jar任务，在integration-tests/build.gradle里添加：

  tasks.named('integrationTest') {
      dependsOn ':app:jar', ':mocks:jar'
  }
  

• 检查并行的JUnit任务是否包含clean逻辑，如果有，要么移除，要么确保clean任务不会干扰Jar任务的输出（比如给clean任务添加mustRunAfter约束）。

2. App项目的缓存键计算存在环境差异 #

本地和GitLab runner的环境差异（比如Java版本、环境变量、Git状态）可能导致Gradle计算出相同的缓存键，但实际输出不同，或者反过来，不同的缓存键导致命中了错误的旧缓存。而mocks项目没有这个问题，说明app项目里有某些动态逻辑没被Gradle正确追踪。

解决/排查： #

• 在本地和GitLab分别执行gradle :app:jar --scan，生成构建扫描后对比两个环境下app:jar任务的输入属性：
  • 重点看是否有环境变量、系统属性、动态生成的文件（比如构建时生成的配置类）没被加入任务的输入；
  • 如果app项目里用了System.getenv()或者project.properties来动态调整构建逻辑，一定要把这些变量添加到任务的inputs.property里，比如：

    tasks.named('compileJava') {
        inputs.property('CI', System.getenv('CI') ?: 'false')
    }
    

• 检查GitLab runner的Java/Gradle版本是否和本地完全一致，哪怕小版本差异都可能导致编译输出不同。

3. GitLab流水线的缓存配置存在问题 #

GitLab的缓存机制如果配置不当，可能导致缓存写入不完整、读取错误，或者多个并行任务共用缓存时出现冲突。

解决/排查： #

• 检查GitLab流水线的cache配置，确保Gradle缓存目录（默认是~/.gradle/caches）被正确缓存，并且设置了唯一的缓存键避免冲突：

  cache:
    key: "gradle-cache-{{ checksum 'gradle/wrapper/gradle-wrapper.properties' }}-{{ checksum 'settings.gradle' }}"
    paths:
      - ~/.gradle/caches/
      - ~/.gradle/wrapper/
  

• 临时禁用远程缓存（如果配置了），只用本地缓存测试，看是否还出现问题——远程缓存的网络波动可能导致app的Jar缓存上传不完整，但mocks的成功上传。
• 检查GitLab runner的权限：确保runner用户对Gradle缓存目录有读写权限，避免因权限不足导致缓存写入失败，进而读取旧的不完整缓存。

4. App项目的Jar/编译任务输入输出声明不完整 #

如果app项目的jar任务没有正确依赖编译任务的输出，或者编译任务的输出目录没被Gradle正确追踪，就会出现缓存命中但build/classes为空的情况。

解决/排查： #

• 确认app项目的jar任务默认依赖compileJava（Gradle默认配置是有的，但如果自定义了Jar任务，需要手动添加）：

  tasks.named('jar') {
      dependsOn tasks.named('compileJava')
  }
  

• 检查是否有自定义的编译逻辑（比如注解处理器、代码生成），确保生成的类目录被加入compileJava任务的输出：

  tasks.named('compileJava') {
      outputs.dir("$buildDir/generated/sources/annotationProcessor/java/main")
  }
  

• 本地测试：执行gradle :app:clean :app:jar --build-cache，然后删除build/classes目录，再执行gradle :app:jar --build-cache，看是否能正确恢复build/classes的内容。如果本地正常，那问题肯定出在GitLab环境的配置上。

最后一步：临时验证 #

如果以上排查都没结果，可以在GitLab流水线的集成测试阶段，先执行gradle :app:jar --no-build-cache，强制重新构建app的Jar，看是否能解决问题——如果能，就坐实了是缓存相关的问题，再回到上面的方向细化排查。

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