docker pull 默认不拉取目标架构镜像，因其仅匹配宿主机架构（runtime.GOARCH），不自动解析 manifest list；需显式启用 buildx 或配置 containerd 才支持多架构拉取。
docker pull 为什么默认不拉取目标架构镜像
因为 docker pull 默认只认当前宿主机架构（runtime.GOARCH），遇到多架构镜像时，它不会主动查 manifest list，而是直接尝试拉取和本地匹配的 platform 的单个镜像。如果远程仓库里没有该架构的 layer，就会报错 no matching manifest for linux/arm64 in the manifest list entries。
这不是 Docker “不支持”，而是它的默认行为偏保守：避免隐式跨架构拉取带来兼容性风险。
- 必须显式启用
docker buildx或配置containerd的imagePullPolicy才能触发 manifest list 解析 - 旧版 Docker（manifest list 解析能力，会直接失败
-
DOCKER_CLI_EXPERIMENTAL=enabled是启用docker manifest子命令的前提，但不影响pull行为本身
如何让 docker pull 自动识别并拉取目标架构镜像
核心是让 Docker 客户端在 pull 前先向 registry 发起 GET /v2/<name>/manifests/<tag></tag></name> 请求，并带上 Accept: application/vnd.docker.distribution.manifest.list.v2+json 头——这才能拿到 manifest list。之后根据本地 buildkit 或 containerd 的 platform 配置做匹配。
- 确保 Docker 版本 ≥ 20.10，且 daemon 启用了
buildkit（"features": {"buildkit": true}在/etc/docker/daemon.json中） - 运行前设置环境变量：
export DOCKER_BUILDKIT=1，否则即使 daemon 开了 buildkit，docker pull仍走 legacy 流程 - 若目标平台不是宿主机架构（比如 x86_64 上拉 arm64），需额外指定：
docker pull --platform linux/arm64 nginx:alpine - 不加
--platform时，Docker 仅依据runtime.GOARCH+runtime.GOOS匹配，不会 fallback 到其他变体（如arm/v7和arm64视为不同 platform）
manifest list 解析失败的典型错误和排查点
最常见的不是“找不到镜像”，而是“找到了但选错了”或者“压根没发对请求”。registry 返回 406 或空 manifest，往往是因为客户端没发对 Accept 头，或镜像根本没推 multi-platform 版本。
- 用
curl -H "Accept: application/vnd.docker.distribution.manifest.list.v2+json" https://registry.hub.docker.com/v2/library/nginx/manifests/alpine手动测——返回 406 说明 registry 不支持或镜像未 push manifest list -
docker manifest inspect nginx:alpine报unauthorized: authentication required？说明你没登录，而该命令不复用docker login凭据，得加-v看详细请求头 - 私有 registry 若用 Harbor，要确认项目已开启
Content Trust或Immutable Tag是否干扰 manifest list 推送 - 使用
buildx build --platform linux/arm64构建后没push，那 remote 就只有单架构镜像，pull当然无法自动切换
buildx 和 containerd 在 manifest 解析中的角色差异
buildx 是构建侧的 multi-platform 能力封装，它自己不参与 docker pull；真正干活的是 containerd 的 imageservice 和 content store。Docker daemon 把 pull 请求转给 containerd 后，由后者决定是否解析 manifest list 并下载对应 platform 的 blob。
- 升级 Docker 但没重启 containerd？可能仍用旧版 resolver，导致
--platform无效 -
containerd配置中[plugins."io.containerd.grpc.v1.cri".registry]若禁用了mirrors或设了错误host_rewrite，会导致 manifest list 请求被转发到错的 endpoint -
ctr images pull --platform linux/arm64 docker.io/library/nginx:alpine可绕过 Docker daemon 直接测试 containerd 行为，适合定位是 client 还是 runtime 问题
manifest list 不是魔法，它依赖 registry 支持、client 请求头正确、runtime 解析逻辑就位——三者缺一不可。最容易被忽略的是 daemon 和 containerd 版本不匹配，或者以为开了 buildkit 就自动生效，其实 pull 路径完全不走 buildkit。
