GitHub Actions中Docker镜像缓存未找到问题求助

问题根源 #

你遇到的缓存未命中，以及直接缓存/var/lib/docker/image无效的原因主要有这几点：

• 首次运行必然无缓存：如果是第一次执行这个Workflow，GitHub Actions还未生成对应缓存键的缓存，提示"Cache not found"是正常现象。若已运行过一次仍未命中，就是以下原因导致。
• Docker存储目录不完整：/var/lib/docker/image仅存储镜像元数据，实际镜像层数据存在/var/lib/docker/overlay2（或对应存储驱动的目录）中，单独缓存image目录无法完整保存镜像内容，恢复后Docker无法识别。
• 权限与环境隔离问题：GitHub Actions的Runner环境是临时的，/var/lib/docker属于root权限目录，actions/cache默认用runner用户操作，可能无法正确读写所有文件；同时每次Runner的Docker守护进程状态不同，直接缓存系统目录易出现兼容性问题。
• 缓存键无内容关联：你的缓存键仅绑定了操作系统，未关联镜像版本或内容哈希，即便缓存成功，后续镜像更新时也无法命中对应缓存，但这不是当前未命中的直接原因。

正确的缓存Docker镜像方案 #

不要直接缓存Docker系统目录，推荐两种可靠方式：

方式1：使用Docker官方动作的缓存机制 #

借助docker/build-push-action内置的缓存功能，无需手动处理目录：

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3

- name: Pull and cache images
  uses: docker/build-push-action@v5
  with:
    context: .
    pull: true
    tags: dummy-tag
    cache-from: type=gha
    cache-to: type=gha,mode=max
    # 用空Dockerfile或简单文件触发缓存拉取
    file: Dockerfile.empty

方式2：手动导出/导入镜像 #

- name: Cache Docker images
  uses: actions/cache@v4
  id: cache-docker
  with:
    path: |
      /tmp/docker-images.tar
    key: docker-layers-${{ runner.os }}-${{ hashFiles('image-list.txt') }}

- name: Load cached images
  if: steps.cache-docker.outputs.cache-hit == 'true'
  run: docker load -i /tmp/docker-images.tar

- name: Pull images and save to cache
  if: steps.cache-docker.outputs.cache-hit != 'true'
  run: |
    docker pull holism/panel
    docker pull node:lts-bookworm-slim
    docker save -o /tmp/docker-images.tar holism/panel node:lts-bookworm-slim

其中image-list.txt可记录要缓存的镜像名称和版本，镜像更新时哈希值变化，会自动生成新缓存键。

额外注意事项 #

• 确保缓存路径有足够空间，GitHub Actions缓存最大支持10GB。
• 避免缓存整个/var/lib/docker目录，不仅体积大，还易导致Docker守护进程异常。

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