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

# 多架构构建 — Buildx 实战

## 概述

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

## Buildx 快速上手

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

## 跨平台构建推送

```bash
# 为 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 自动传入）：

```dockerfile
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 插件时，可以手动安装：

```bash
# 注册 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 节点混合架构时的调度考量