容器与云原生 / 系统课时
构建多平台镜像
构建多平台镜像
同一应用如果要同时运行在 x86_64 服务器、Apple Silicon 开发机和 ARM 边缘设备上,就不能只发布单一架构镜像。本节使用 Docker Buildx 一次构建 linux/amd64 与 linux/arm64 镜像,并推送为同一个标签下的多平台镜像清单。
学习目标
- 创建并启用支持多平台构建的 Buildx builder。
- 使用
--platform一次构建并推送多个架构镜像。 - 用镜像清单检查同一标签是否包含预期的平台。
多平台镜像解决什么问题
普通 docker build 通常只针对当前主机架构生成镜像。例如在 amd64 主机上构建出的镜像,若其中包含与架构相关的二进制文件,直接拿到 arm64 主机运行可能失败。
多平台镜像把多个架构版本挂在同一个标签下。拉取时,Docker 会根据当前主机平台,从镜像清单中选择匹配的具体镜像,因此使用者仍然可以执行同一条 docker pull 命令。

准备可复现的构建示例
在空目录中创建下面的 Dockerfile。示例只依赖 Alpine,并把构建时识别到的平台写入文件,便于之后验证实际构建了哪些目标架构。
FROM alpine:3.22
ARG TARGETPLATFORM
RUN printf '%s\n' "$TARGETPLATFORM" > /target-platform.txt
CMD ["cat", "/target-platform.txt"]这是配置文件而不是独立命令。构建成功后,容器启动会输出镜像构建时对应的目标平台。
创建并检查 Buildx builder
先创建一个使用 docker-container 驱动的 builder。这个驱动会在独立的 BuildKit 容器中执行构建,更适合一次处理多个目标平台。
docker buildx create --name multiplatform --driver docker-container --use
docker buildx inspect --bootstrap预期输出
Name: multiplatform
Driver: docker-container
Status: running
Platforms: linux/amd64, linux/amd64/v2, ..., linux/arm64, ...平台列表会因 Docker、BuildKit、宿主机和仿真能力不同而变化;关键是 Status 为 running,并且输出中包含计划构建的平台。如果缺少 linux/arm64 或其他目标架构,应先检查 Docker Desktop 的仿真支持,或在 Linux 主机上正确安装并注册 binfmt/QEMU。
构建并推送两个平台
多平台结果不能用传统单平台镜像那样简单地同时载入本地镜像存储,因此最直接的做法是使用 --push 写入 Registry。将下面的占位值替换为你可推送的仓库地址和命名空间。
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t <REGISTRY>/<NAMESPACE>/platform-demo:1.0 \
--push \
.预期输出
[+] Building <TIME> (<ID>/<ID>) FINISHED
...
=> exporting manifest list sha256:<ID>
=> pushing layers
=> pushing manifest for <REGISTRY>/<NAMESPACE>/platform-demo:1.0实际耗时、步骤编号和摘要值会不同。这里最重要的是构建过程没有报错,并且最终出现 manifest list 或 image index 的导出与推送信息。
验证镜像清单
推送完成后,不需要在每种 CPU 上都实际拉取一次,先用 Buildx 查看远端镜像清单即可。
docker buildx imagetools inspect <REGISTRY>/<NAMESPACE>/platform-demo:1.0预期输出
Name: <REGISTRY>/<NAMESPACE>/platform-demo:1.0
MediaType: application/vnd.oci.image.index.v1+json
Digest: sha256:<ID>
Manifests:
Name: <REGISTRY>/<NAMESPACE>/platform-demo:1.0@sha256:<ID>
Platform: linux/amd64
Name: <REGISTRY>/<NAMESPACE>/platform-demo:1.0@sha256:<ID>
Platform: linux/arm64只要清单中同时出现 linux/amd64 和 linux/arm64,同一个标签就已经具备多平台分发能力。此后不同架构主机执行普通 docker pull 时,会自动选择与自身平台匹配的镜像;只有在调试或强制测试时,才需要显式指定 --platform。