按平台构建是什么
--platform 用来指定构建产物的目标运行平台，例如 linux/amd64、linux/arm64。不写时产物平台与当前构建器一致。BuildKit 会为列表里的每个平台各构建一份，推送仓库时合并成一份多平台清单（manifest list），用户拉取时按自己的架构自动匹配。跨架构构建靠 binfmt/QEMU 模拟或原生构建节点完成，模拟能跑通但速度明显更慢。
基本信息
| 适用环境 | Docker 23+ 自带 buildx；Linux、macOS、WSL2 均可 |
|---|---|
| 语法 | docker buildx build --platform linux/arm64 --load -t 名称 . |
| 前置条件 | docker-container 驱动构建器；跨架构需注册 binfmt 或使用原生节点 |
| 导出方式 | --load 导入本地镜像库；--push 直推仓库（多平台只能 push） |
典型使用场景
- 在 x86 开发机构建 linux/arm64 产物，提前验证 ARM 节点上的行为
- 为树莓派、ARM 云主机等异构节点准备可运行镜像
- CI 中一次构建多平台并推送，用户 pull 时自动取到匹配架构
- 排查拉错架构问题：核对产物平台与目标节点是否一致
- 在 Dockerfile 里按 TARGETARCH 分支安装对应架构的依赖包
单平台与多平台示例
单平台与多平台示例
# 单平台：构建并导入本地镜像库（docker-container 驱动必须加 --load）
docker buildx build --platform linux/amd64 --load -t app/web:1.0 .
docker inspect -f '{{.Architecture}}' app/web:1.0 # 核对产物架构而不是宿主架构
# 多平台：直接推送仓库，同时生成多平台清单
docker buildx build --platform linux/amd64,linux/arm64 --push -t reg.example.com/app/web:1.0 .
docker buildx imagetools inspect reg.example.com/app/web:1.0 # 查看清单包含的平台平台值怎么读
| 写法 | 含义 | 注意 |
|---|---|---|
| linux/amd64 | x86_64 服务器与 PC | 最常见的默认架构 |
| linux/arm64 | ARM 64 位：ARM 云主机、Apple 芯片桌面环境 | 模拟构建速度较慢 |
| linux/arm/v7 | 32 位 ARM，如树莓派 3 | 部分基础镜像不提供该平台 |
| $BUILDPLATFORM | 构建机自身平台，用于编译阶段 | 编译阶段提速 |
| $TARGETPLATFORM | 目标平台，用于运行阶段 | 必须在此前用 ARG 声明 |
多平台构建只能 --push：本地镜像库一份镜像只对应一个架构。要本地验证某个架构，就单独构建那一个平台并加 --load。
Docker Desktop 与多数云构建服务已内置跨架构支持；裸 Linux 主机上跨架构构建要先注册 binfmt 处理器并确认内核已挂载 binfmt_misc。