多架构镜像是什么
同一个镜像标签在多架构场景下并不指向一个镜像，而是指向一份“清单列表”（manifest list，OCI 规范里叫镜像索引），里面按操作系统与架构分别记录对应的镜像摘要。拉取时运行时读取本机平台，自动挑出匹配的那一份，所以同一个标签在 x86 与 ARM 上跑的是两个不同构建产物。排查架构相关问题、做多平台发布之前，先用清单查看工具确认这份清单里到底有哪些平台。
基本信息
| 适用平台 | Docker 20.10 起 docker manifest 可直接使用，老版本 CLI 需开启实验特性 |
|---|---|
| 推荐工具 | docker buildx imagetools inspect，默认可用且输出更直观 |
| 清单内容 | 按 os、architecture、variant 列出各平台镜像的摘要与大小 |
| 拉取规则 | 运行时按本机平台自动选择，可用 --platform 显式指定 |
| 推送规则 | 多平台镜像要用 buildx --platform 构建并直接推送，本地仓库看不到 |
| 典型报错 | exec format error 表示拉到的镜像与当前平台不匹配 |
典型使用场景
- 确认某个官方镜像是否包含 arm64，避免在 ARM 服务器上踩坑
- 多平台发布前检查清单里的平台是否齐全、摘要是否最新
- 排查 exec format error 时，先看镜像清单再考虑 binfmt 兜底
- 给不同架构的节点统一使用同一个标签，降低发布配置复杂度
- 对比同一标签不同架构镜像的大小，评估分发与存储成本
使用示例
使用示例
docker manifest inspect nginx:1.27 | head -40 # 看清单里的平台列表
docker buildx imagetools inspect nginx:1.27 # 推荐：输出更直观
docker buildx imagetools inspect myapp:1.2.3 --raw | head -40 # 看原始清单 JSON
docker buildx build --platform linux/amd64,linux/arm64 -t myapp:1.2.3 --push . # 打多平台并推送
docker pull --platform linux/arm64 nginx:1.27 # 指定平台拉取用于验证常见平台字段
| 字段 | 含义 | 注意 |
|---|---|---|
| os | 操作系统 | linux 与 windows 不能混用同一清单 |
| architecture | 架构 | amd64、arm64、arm 等 |
| variant | 架构变体 | 如 arm64 的 v8 |
| mediaType | 清单类型 | 索引类型表示这是多架构清单 |
| digest | 镜像摘要 | 平台不同摘要不同，可用于核对是否更新 |
在 ARM 机器上拉到 amd64 镜像会报 exec format error：先确认清单里有没有对应架构，再考虑用 binfmt/QEMU 兜底，后者性能有损耗。
本地 docker build 生成的镜像只有本机架构：要出多平台产物必须用 buildx 指定平台列表，并直接推送或导出，本地镜像列表里不会出现多架构条目。