多架构构建与推送
用一条 buildx 命令产出 amd64、arm64 等多个平台的镜像并推送到仓库，拉取端按自身架构自动选择对应变体。这是 CI 里发布镜像的标准做法，前提是构建器具备对应平台的构建能力。
基本信息
| 前置条件 | buildx 实例配 docker-container 驱动，并已登录目标仓库 |
|---|---|
| 命令骨架 | buildx build --platform ... --tag ... --push |
| 平台写法 | linux/amd64,linux/arm64，多个平台用逗号分隔 |
| 验证方式 | docker buildx imagetools inspect 镜像:标签 查看清单 |
| 标签策略 | 同一 tag 指向清单列表，也可按架构分别打 tag |
典型使用场景
- 发布同时支持 x86 与 ARM 服务器的镜像，一条命令产出全部平台
- 边缘设备与云端节点共用同一个仓库 tag，简化部署脚本
- 开发机为 ARM、生产机为 x86 的团队统一发布流程
- 迁移到 ARM 云主机时验证既有镜像能否提供对应架构版本
- 交付给客户的多架构镜像包，减少按架构分别维护的成本
- 把多平台构建放进发布流水线，日常开发只构建本机平台
示例
示例
docker buildx create --name multiarch --driver docker-container --use
docker login registry.example.com
docker buildx build \
--platform linux/amd64,linux/arm64 \
--tag registry.example.com/app/web:1.0 \
--tag registry.example.com/app/web:latest \
--push .
docker buildx imagetools inspect registry.example.com/app/web:1.0 # 核对平台清单前置条件与不满足时的表现
| 前置项 | 确认方式 | 不满足时的表现 |
|---|---|---|
| 构建器支持多平台 | docker buildx ls 看平台列表 | 报不支持目标平台 |
| binfmt 或原生节点 | 容器内能执行对应架构二进制 | exec format error |
| 仓库登录 | docker login 成功 | 推送阶段报 401 或 denied |
| tag 推送权限 | 账号具备目标仓库写权限 | 推送被拒绝 |
| 网络出口 | 能访问基础镜像与仓库 | 拉取或推送超时 |
推送后该 tag 指向的是多平台清单，不同架构的节点拉同一个 tag 会各自拿到匹配的镜像，使用者不必关心架构差异。
构建耗时随平台数量成倍增加，日常开发只构建本机平台，多平台放到发布流水线里执行更合理。
验证清单最直接的办法是 imagetools inspect：能列出多个平台说明多架构构建成功，只列一项说明实际只产出了单平台。