GitHub Action中Gradle子项目缓存失败问题求助

针对你单体仓库中后端Gradle缓存始终提示“gradle cache is not found”的问题，以下是几个针对性的排查和解决步骤：

1. 确认本地构建缓存配置的有效性 #

先检查settings.gradle.kts中的构建缓存配置是否正确启用，确保本地缓存目录路径准确：

buildCache {
    local {
        enabled = true
        directory = File(rootDir, ".gradle/cache")
        removeUnusedEntriesAfterDays = 30
    }
}

注意：本地构建缓存仅在当前Runner实例生效，GitHub Actions的Runner是临时容器，必须配合GitHub的缓存机制才能持久化缓存内容。

2. 改用Gradle官方Action处理缓存 #

actions/setup-java的cache-dependency-path主要针对Maven缓存，对Gradle的支持有限。推荐使用官方的gradle/gradle-build-action，它专门优化了Gradle在CI环境中的缓存逻辑，自动处理依赖、构建缓存、Wrapper等内容：

steps:
  - uses: actions/checkout@v4

  # 保留你现有的前端NPM缓存配置
  - name: Cache node modules
    uses: actions/cache@v4
    with:
      path: ~/.npm
      key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
      restore-keys: |
        ${{ runner.os }}-node-

  # 后端使用Gradle官方Action管理缓存
  - name: Setup Gradle
    uses: gradle/gradle-build-action@v3
    with:
      gradle-version: '8.x' # 替换为你的Gradle版本，或留空让Action自动识别Wrapper版本

  - name: Build backend
    run: ./gradlew build --no-daemon

3. 手动配置actions/cache适配Gradle（若坚持用setup-java） #

如果不想切换到官方Gradle Action，需要明确指定所有Gradle相关的缓存路径，避免遗漏：

steps:
  - uses: actions/checkout@v4

  - name: Cache Gradle resources
    uses: actions/cache@v4
    with:
      path: |
        ~/.gradle/caches
        ~/.gradle/wrapper
        .gradle/cache # 对应你settings.gradle.kts中配置的本地缓存目录
      key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
      restore-keys: |
        ${{ runner.os }}-gradle-

  - name: Setup Java
    uses: actions/setup-java@v4
    with:
      java-version: '17' # 替换为你的Java版本
      distribution: 'temurin'
      # 此处无需再配置cache-dependency-path，已通过actions/cache覆盖

  - name: Build backend
    run: ./gradlew build --build-cache --no-daemon

注意：hashFiles要包含所有Gradle配置文件，确保缓存键能准确反映依赖或配置的变化。

4. 验证缓存状态 #

在GitHub Action的运行日志中，查找Cache restored successfully或Cache saved successfully的条目，确认Gradle相关路径被正确缓存。如果仍有问题，可在构建前添加调试步骤检查缓存目录：

- name: Check Gradle cache directories
  run: |
    ls -la ~/.gradle/caches
    ls -la .gradle/cache

通过输出确认缓存目录是否有内容，判断缓存是否被正确恢复。

5. 确保构建命令启用缓存 #

运行Gradle命令时，避免使用--no-build-cache参数，可显式添加--build-cache参数确保缓存生效：

./gradlew build --build-cache --no-daemon

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