如何解决GitHub Actions中Docker构建重复下载Maven依赖的问题

问题背景 #

已实现Dockerfile的多层缓存，但在GitHub Actions构建时，Maven依赖始终会重新下载；本地Docker环境则能正常缓存依赖。当前使用docker/build-push-action@v5并配置了cache-from/cache-to: type=gha，Dockerfile中也通过--mount=type=cache挂载了Maven本地仓库。

核心原因 #

Docker Buildx的type=gha缓存默认只持久化构建阶段的镜像层，而--mount=type=cache属于构建临时缓存，不会自动被cache-to持久化到GitHub Actions的缓存存储中。本地环境因Docker daemon会保留临时缓存，所以能正常复用；但CI环境每次都是全新构建环境，临时缓存无法跨构建保留。

解决方案 #

1. 调整Dockerfile的缓存挂载配置 #

修改Maven构建的RUN命令，给缓存添加唯一ID并设置共享模式，让Buildx能识别并持久化这个缓存：

FROM maven:3-amazoncorretto-17 AS builder
COPY pom.xml .
COPY src src
# 添加id和sharing=locked，确保缓存可被Buildx持久化
RUN --mount=type=cache,target=/root/.m2,id=maven-cache,sharing=locked mvn -f pom.xml package -Dmaven.test.skip=true
RUN java -Djarmode=layertools -jar target/*.jar extract

FROM amazoncorretto:17-alpine
COPY --from=builder dependencies/ ./
COPY --from=builder snapshot-dependencies/ ./
COPY --from=builder spring-boot-loader/ ./
COPY --from=builder application/ ./
RUN wget -O dd-java-agent.jar "https://dtdg.co/latest-java-tracer"
ENTRYPOINT ["java", "org.springframework.boot.loader.JarLauncher"]

• id=maven-cache：为缓存项命名，让Buildx关联到这个特定缓存
• sharing=locked：避免多进程同时操作缓存导致的数据不一致

2. 优化GitHub Actions的缓存配置 #

在docker/build-push-action中，指定缓存范围并启用mode=max，确保挂载的临时缓存被包含到持久化缓存中：

- name: Setup Docker
  uses: docker/setup-buildx-action@v3

- name: Build the Docker image
  uses: docker/build-push-action@v5
  with:
    labels: |
      ${{ steps.docker-metadata.outputs.labels }}
    tags: |
      ${{ env.ECR_DOCKER_IMAGE_TAG_URL || env.DOCKER_IMAGE_URL }}
    file: ${{ inputs.dockerfile-name }}
    context: .
    load: true
    # 添加scope区分不同分支的缓存，避免互相干扰
    cache-from: type=gha,scope=${{ github.ref_name }}
    # mode=max让Buildx缓存尽可能多的内容，包括挂载的临时缓存
    cache-to: type=gha,scope=${{ github.ref_name }},mode=max
    build-args: |
      GITHUB_HEAD_REF="${{ github.head_ref }}"
      GITHUB_REF_NAME="${{ github.ref_name }}"
      GITHUB_RUN_ID="${{ github.run_id }}"
      GITHUB_RUN_NUMBER="${{ github.run_number }}"
      GITHUB_SHA="${{ github.sha }}"

• scope=${{ github.ref_name }}：给缓存添加分支/标签维度，避免不同分支的缓存互相覆盖
• mode=max：扩展缓存范围，将构建过程中的临时挂载缓存也纳入持久化范围

3. 进一步优化依赖缓存效率（可选） #

调整Dockerfile的构建顺序，先执行依赖预下载，再复制源码，最大化利用Docker层缓存：

FROM maven:3-amazoncorretto-17 AS builder
# 先复制pom.xml，仅当pom变化时才会重新处理依赖
COPY pom.xml .
# 预下载所有依赖到缓存
RUN --mount=type=cache,target=/root/.m2,id=maven-cache,sharing=locked mvn dependency:go-offline -Dmaven.test.skip=true
# 再复制源码，源码变化不会触发依赖下载
COPY src src
RUN --mount=type=cache,target=/root/.m2,id=maven-cache,sharing=locked mvn -f pom.xml package -Dmaven.test.skip=true
RUN java -Djarmode=layertools -jar target/*.jar extract

# 后续阶段不变...

验证方法 #

• 触发GitHub Actions构建后，查看构建日志，确认Maven构建步骤中出现Using cache相关提示
• 对比构建耗时，确认依赖下载环节被跳过，构建时间显著缩短

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