Github Actions中Docker tag报错‘No such image’排查求助

核心原因 #

Docker Buildx默认在独立的builder实例中构建镜像，构建产物不会自动同步到本地Docker daemon，直接执行docker tag自然找不到目标镜像。以下是针对性的解决方案：

1. 让Buildx将镜像加载到本地Docker daemon #

在docker buildx build命令中添加--load参数，构建完成后镜像会被加载到本地，后续docker tag就能识别到：

- name: Build Docker image
  run: |
    docker buildx build \
      --tag ${{ env.IMAGE_NAME }}:latest \
      --load \
      .

注意：--load仅支持单一平台镜像构建；如果需要构建多平台镜像，需改用--push直接推送仓库，或用--output type=docker指定输出到本地。

2. 直接用Buildx完成构建+推送，跳过本地tag步骤 #

无需单独执行docker tag，直接在Buildx命令中指定GCP Artifact Registry的完整镜像标签，加上--push参数一步完成构建推送：

- name: Build and push with Buildx
  run: |
    docker buildx build \
      --tag ${{ env.GCP_AR_REPO }}/${{ env.IMAGE_NAME }}:latest \
      --platform linux/amd64,linux/arm64 \
      --push \
      .

其中${{ env.GCP_AR_REPO }}需替换为你的GCP仓库地址，格式如us-central1-docker.pkg.dev/你的项目ID/你的仓库名。

3. 检查Buildx builder实例配置 #

若使用了远程或非默认builder实例，可能导致镜像存储在远端缓存而非本地。可先查看当前builder：

docker buildx ls

如果需要创建本地专属builder：

docker buildx create --use --name local-builder --driver docker-container

Buildx构建后镜像的存储位置 #

• 加了--load或--output type=docker：镜像存储在本地Docker daemon的镜像仓库中，用docker images可查看，和普通docker build产物位置一致。
• 未加上述参数：镜像仅存在于Buildx builder实例的临时缓存中，本地Docker daemon无法识别，这也是触发"No such image"错误的常见场景。

额外GCP配置检查 #

1. 确保Github Actions已完成GCP认证并配置Docker访问：

- name: Authenticate to GCP
  uses: google-github-actions/auth@v1
  with:
    credentials_json: ${{ secrets.GCP_SERVICE_ACCOUNT_KEY }}

- name: Configure Docker for GCP Artifact Registry
  run: |
    gcloud auth configure-docker ${{ env.GCP_REGION }}-docker.pkg.dev

2. 确认镜像标签中的区域、项目ID、仓库名完全匹配GCP Artifact Registry的实际配置，避免拼写错误。

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