all-in-kingsoft/hhs/MS/05-部署运维/01-容器化/02-多架构构建.md

tags, create time

tags	create time
docker multi-arch buildx cross-platform	2026-05-18 00:45

多架构构建 — Buildx 实战

概述

随着 Apple Silicon 和 ARM 服务器普及，一个平台只能构建一种架构的镜像已无法满足需求。Docker Buildx 让我们一次构建、全平台运行。本文档讲解多架构构建的核心操作和原理。

Buildx 快速上手

# 启用 buildx 并创建 multi-platform builder
docker buildx create --name mybuilder --use
docker buildx inspect --bootstrap

跨平台构建推送

# 为 amd64 + arm64 同时构建并推送到仓库
docker buildx build \
    --platform linux/amd64,linux/arm64 \
    -t harbor.example.com/app/server:v1.2.3 \
    --push \
    .

[!note] manifest list 原理

多架构镜像本质上是一个 manifest list——它不直接包含二进制文件，而是记录每个架构对应的镜像 digest。拉取时，客户端根据自身平台自动选择正确的变体。可以用 docker buildx imagetools inspect <image> 查看完整列表。

不同场景的构建策略

场景	策略	命令
开发阶段	只构建本机架构 (linux/arm64)，速度最快	docker buildx build --platform linux/arm64 .
CI 流水线	构建全平台 (linux/amd64,linux/arm64)，统一推送	--platform linux/amd64,linux/arm64 --push
临时调试	--load 仅构建本地可用	docker buildx build --load .

Go 跨平台编译提示

在 Dockerfile 中使用 ARG TARGETARCH（Buildx 自动传入）：

FROM golang:1.22-alpine AS builder

ARG TARGETARCH
ARG TARGETPLATFORM

RUN echo "Building for: $TARGETARCH ($TARGETPLATFORM)"

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN CGO_ENABLED=0 GOOS=linux GOARCH=$TARGETARCH \
    go build -a -ldflags "-s -w" -o server-$TARGETARCH .

[!info] 环境变量对照

变量	示例值	说明
TARGETARCH	amd64, arm64	CPU 架构
TARGETOS	linux, darwin	操作系统
TARGETPLATFORM	linux/amd64, linux/arm64	完整平台标识

补充：QEMU 模拟（CI 中的备用方案）

当你的 CI 环境不支持 Buildx QEMU 插件时，可以手动安装：

# 注册 QEMU 模拟器
docker run --privileged --rm tonistiigi/binfmt --install all

# 之后即可通过 qemu 模拟不同平台构建（速度较慢）
docker buildx build --platform linux/arm64 -t my-app:arm64 .

[!warning] 模拟构建 vs 原生交叉编译

QEMU 模拟可以运行在其他架构上，但构建速度极慢（通常比原生慢 5~10 倍）。生产环境推荐使用 Go 原生交叉编译（GOOS=linux GOARCH=arm64），零依赖且秒级完成。只在需要 C 扩展的场景才考虑 QEMU 模拟。

关联笔记

• ../01-容器化/01-Dockerfile最佳实践 — 多阶段构建 + BuildKit 特性
• ../hhs/MS/05-部署运维/02-Kubernetes — K8s 节点混合架构时的调度考量