Docker Buildx构建ARM64镜像被识别为清单列表却无法检视的问题

核心错误原因 #

1. ARM64镜像被推为Manifest List而非单一架构镜像
   你在ARM64构建命令中使用了--output type=registry，这个参数会让Docker Buildx默认推送一个单平台的Manifest List（即使你指定了--platform=linux/arm64）。而docker manifest create命令要求传入的是单一架构的镜像引用，不能是Manifest List，因此触发了is a manifest list的错误。

2. Manifest Inspect失败的原因
   GitHub Actions环境中的Docker客户端没有实时同步Registry的最新状态，加上Docker Hub可能存在缓存延迟，导致你执行docker manifest inspect时无法立即找到刚推送的镜像。

修正方案 #

方案1：改用--push参数推送单一架构镜像（推荐）

将ARM64构建命令中的--output type=registry替换为--push，Buildx会直接推送单一ARM64架构的镜像Manifest，而非Manifest List：

# 修正后的ARM64构建&推送命令
docker buildx build . \
    --tag my-repo/my-image-arm64:<some-tag> \
    --platform=linux/arm64 \
    --push \
    --build-arg tarball_uri=<link-to-arm64-tarball> \
    --cache-to type=registry,ref=my-repo/my-image-cache,mode=max \
    --cache-from type=registry,ref=my-repo/my-image-cache,mode=max

方案2：强制推送单一Manifest（保留--output type=registry）

如果需要保留--output type=registry，可以添加manifest=index=false参数，强制Buildx推送单一架构的Manifest：

docker buildx build . \
    --tag my-repo/my-image-arm64:<some-tag> \
    --platform=linux/arm64 \
    --output type=registry,manifest=index=false \
    --build-arg tarball_uri=<link-to-arm64-tarball> \
    --cache-to type=registry,ref=my-repo/my-image-cache,mode=max \
    --cache-from type=registry,ref=my-repo/my-image-cache,mode=max

关于Manifest Inspect的补充处理 #

在GitHub Actions中，推送完成后建议先拉取镜像Manifest再执行检查，或者增加短暂等待避免Registry同步延迟：

# 拉取Manifest后再执行检查
docker manifest pull my-repo/my-image-arm64:<some-tag>
docker manifest inspect my-repo/my-image-arm64:<some-tag>

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