一次构建多平台镜像
buildx 把构建提升为一次性产出多个平台镜像并直接推送的能力。关键限制在于多架构镜像不能通过本地镜像库加载：一个标签下对应多个平台的清单，本地加载只接受单平台产物，所以应当使用 --push 推送到仓库，或用显式输出把产物导出到目录。
基本信息
| 创建构建器 | docker buildx create --use --name multi，跨架构构建依赖模拟支持 |
|---|---|
| 多平台参数 | --platform linux/amd64,linux/arm64，可继续追加 |
| 输出方式 | --push 直接推送仓库；--load 只支持单平台 |
| 驱动要求 | docker-container 驱动才支持多平台输出 |
| 缓存 | 可挂载缓存或用仓库缓存，避免每次完全重建 |
| 验证方式 | docker buildx imagetools inspect 查看清单包含哪些平台 |
典型使用场景
- 同一镜像需要同时支持 x86 与 ARM 服务器
- 面向国产化或 ARM 环境交付，需要 arm64 版本镜像
- CI 中统一构建并推送一个多架构标签，部署侧按节点架构自动选择
- 开发机是 ARM 而生产是 x86，需要一次构建两处可用
- 排查已有镜像缺失某个平台清单，导致部分节点拉取失败
完整流程
完整流程
docker buildx create --use --name multi --driver docker-container
docker buildx inspect --bootstrap # 初始化构建器并确认可用
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t registry.example.com/team/app:1.2.3 \
--push . # 多平台必须推送或显式输出
docker buildx imagetools inspect registry.example.com/team/app:1.2.3 # 核对清单输出方式对比
| 输出参数 | 适用场景 | 限制 |
|---|---|---|
| --push | 多平台构建后交付 | 需先登录目标仓库 |
| --load | 单平台本地验证 | 多平台时直接报错 |
| --output type=registry | 与 --push 等价的显式写法 | 需指定完整目标地址 |
| --output type=local,dest=路径 | 导出构建产物到目录 | 导出的是文件不是镜像，需自行打包 |
| --cache-to 与 --cache-from | 加速重复构建 | 需仓库或存储支持缓存格式 |
跨架构构建经常依赖模拟执行：编译耗时可能是原生数倍，构建超时高发。流水线上要预留足够时间，或为常用架构准备原生构建节点，否则表现为「本地能过、流水线总超时」。
多架构镜像的正确性要两层验证：先用 imagetools inspect 确认清单里包含目标平台，再在对应架构的机器上实际拉取并启动一次，避免出现清单存在但镜像层不可用的情形。