GitHub Actions工作流中复用Docker镜像避免重复拉取的方法

核心思路 #

GitHub Actions中每个Job（包括矩阵实例）默认会独立拉取容器镜像，但可以通过预拉取镜像并缓存、复用本地镜像两种方式避免重复拉取，具体方案如下：

方案一：前置Job拉取镜像并缓存（跨Job复用） #

通过一个前置Job将容器镜像导出为tar包，存入GitHub Actions缓存，后续所有Job直接从缓存加载镜像，无需重复拉取远程镜像。

示例配置：

jobs:
  # 前置Job：拉取镜像并存入缓存
  cache-image:
    runs-on: ubuntu-latest
    steps:
      - name: Pull target container image
        run: docker pull alpine/hello-world
      
      - name: Export image to tar file
        run: docker save -o hello-world.tar alpine/hello-world
      
      - name: Cache image tar
        uses: actions/cache@v3
        with:
          path: hello-world.tar
          key: ${{ runner.os }}-hello-world-image

  # Job1：从缓存加载镜像并执行步骤
  job1:
    needs: cache-image
    runs-on: ubuntu-latest
    steps:
      - name: Retrieve cached image tar
        uses: actions/cache@v3
        with:
          path: hello-world.tar
          key: ${{ runner.os }}-hello-world-image
      
      - name: Load image into docker
        run: docker load -i hello-world.tar
      
      - name: Run commands in container
        uses: docker://alpine/hello-world
        with:
          entrypoint: sh
          args: -c "你的业务命令"

  # Job2：矩阵Job，复用缓存镜像
  job2:
    needs: cache-image
    runs-on: ubuntu-latest
    strategy: 
      matrix: value: ['abc','def']
    steps:
      - name: Retrieve cached image tar
        uses: actions/cache@v3
        with:
          path: hello-world.tar
          key: ${{ runner.os }}-hello-world-image
      
      - name: Load image into docker
        run: docker load -i hello-world.tar
      
      - name: Run matrix-specific commands
        uses: docker://alpine/hello-world
        with:
          entrypoint: sh
          args: -c "处理矩阵参数：${{ matrix.value }}"

方案二：Job内检查本地镜像（同runner矩阵实例复用） #

如果矩阵Job的多个实例运行在同一个runner上（比如自托管runner），可以在步骤前先检查本地是否存在目标镜像，仅在缺失时拉取，避免同一runner上重复拉取。

示例配置：

jobs:
  job2:
    runs-on: ubuntu-latest
    strategy: 
      matrix: value: ['abc','def']
    steps:
      - name: Check and pull image if missing
        run: |
          if ! docker image inspect alpine/hello-world > /dev/null 2>&1; then
            docker pull alpine/hello-world
          fi
      
      - name: Run matrix steps in container
        uses: docker://alpine/hello-world
        with:
          entrypoint: sh
          args: -c "处理矩阵参数：${{ matrix.value }}"

注意事项 #

• GitHub托管的runner是临时实例，每个Job可能分配到全新的runner，因此跨Job复用必须依赖缓存；矩阵Job若并行执行，大概率会分配到不同runner，这种情况下方案二无法生效，建议优先用方案一。
• 缓存key需包含操作系统和镜像标识（如标签、哈希），避免不同镜像的缓存冲突；若镜像更新，需修改缓存key以触发新的缓存。

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