imagetools 是什么
imagetools 是 buildx 的一个子命令，用来直接查询与操作远端仓库里的镜像清单。它不需要把镜像拉到本地，就能看到某个标签包含哪些平台条目、每条对应的摘要与体积。发布多架构镜像后，用它核对清单是否完整是最快的方式，也是排查「某些节点拉到错误架构」问题的入口。
基本信息
| 查询语法 | docker buildx imagetools inspect 仓库/镜像:标签 |
|---|---|
| 原始输出 | docker buildx imagetools inspect --raw 镜像 打印清单原文 |
| 创建清单 | docker buildx imagetools create 把多个镜像合并成一个多平台标签 |
| 操作对象 | 远端仓库内容，不是本地镜像库 |
| 前置条件 | 私有仓库需先 docker login；网络可达仓库 |
| 适用版本 | 随 buildx 提供，较新的 Docker 版本自带 |
典型使用场景
- 发布后核对多架构清单是否包含全部目标平台
- 确认用户实际会拉到的镜像摘要，与流水线记录比对
- 把分别构建的各架构镜像合并成一个统一标签
- 排查架构不匹配：确认清单里是否存在目标平台条目
- 巡检历史标签：确认旧版本仍可被各平台拉取
查询与创建
查询与创建
# 查看某个标签的多平台清单：平台、摘要、体积一目了然
docker buildx imagetools inspect nginx:1.27-alpine
docker buildx imagetools inspect registry.example.com/app/web:1.0
# 查看清单原文（需要脚本化解析时使用）
docker buildx imagetools inspect --raw registry.example.com/app/web:1.0 | head -40
# 把已分别推送的各架构镜像合并成一个多平台标签
docker buildx imagetools create -t registry.example.com/app/web:1.0 \
registry.example.com/app/web:1.0-amd64 \
registry.example.com/app/web:1.0-arm64
# 合并后再核对一次清单
docker buildx imagetools inspect registry.example.com/app/web:1.0输出怎么读
| 字段 | 含义 | 异常信号 |
|---|---|---|
| MediaType | 清单类型（多平台清单或单镜像） | 显示单镜像时说明不是多架构 |
| Platform | 平台条目 | 缺少目标平台即为不完整 |
| Digest | 该平台镜像摘要 | 与流水线记录不一致需排查 |
| Size | 该条目体积 | 异常小可能是空层镜像 |
| Manifests 段落 | 包含的平台列表 | 只有一项时确认是否漏推 |
| Name/标签 | 查询目标 | 注意区分缓存标签与发布标签 |
本地镜像信息用 docker image inspect 查看，imagetools 面向远端仓库；两者信息源不同，排查时先确认自己查的是哪一侧。
合并清单不会复制层文件，只是新增一份指向已有摘要的清单，因此操作很快，也不会额外占用仓库空间。