MAC M4 上构建多架构镜像（x86/arm64）

一、docker build、buildx、BuildKit 

1、句话先立住全局认知

BuildKit 是新一代构建引擎（内核）
docker build 是传统构建入口（前端 CLI）
docker buildx 是 BuildKit 的高级 CLI + 多架构调度器

三者不是并列关系，而是层层演进、彼此包含

2、演变阶段

第一阶段：docker build（Legacy Builder）

特征

• 单线程

• 串行执行 Dockerfile

• 每一层必须完整生成

• 不支持多平台

• 缓存命中率低

第二阶段：BuildKit（构建引擎革命）

Docker 在 2019 年引入 BuildKit，目标是：把“构建”从一个 CLI 命令，变成一个可并发、可缓存、可分布式的构建引擎

BuildKit 带来的质变能力

能力	说明
DAG 并发执行	不再一层一层顺序跑
精准缓存	基于内容 hash
Remote cache	cache 可存 S3 / registry
Secret / SSH mount	不落盘
多平台支持	构建阶段就区分 arch

第三阶段：docker buildx（BuildKit 的“操控台”）

BuildKit 很强，但：

• Docker 原生 CLI 没法管理 builder

• 没法做多平台调度

• 没法用 QEMU / remote builder

👉 docker buildx 就是为了解决这些问题而生

逻辑关系图（非常重要）

┌────────────────────────┐
│    docker build        │  ← 老入口
│  (legacy / limited)    │
└───────────┬────────────┘
            │
            │ DOCKER_BUILDKIT=1
            ↓
      ┌──────────────┐
      │  BuildKit    │  ← 构建引擎（核心）
      └──────────────┘


┌───────────────────────────────┐
│         docker buildx         │  ← 新入口（推荐）
│  - builder 管理               │
│  - 多平台                     │
│  - cache / push / bake        │
└──────────────┬────────────────┘
               ↓
          ┌──────────────┐
          │  BuildKit    │
          └──────────────┘

结论：

只要你涉及 M1 / x86 / CI / 多平台，一律用 buildx

二、环境准备

1、安装了docker desktop 和 OrbStack 两个应用

OrbStack	日常运行容器（轻量、快）	默认 builder 驱动为 docker，不支持多平台构建
Docker Desktop	构建镜像（尤其 x86）	提供完整 Buildx + QEMU + Rosetta 支持

构建失败，需要创建一个 dd-builder

docker buildx create \
  --name dd-builder \
  --driver docker-container \
  --use \          # ✅ 加上 --use，省去后续切换
  --bootstrap \
  unix:///Users/$(whoami)/Library/Containers/com.docker.docker/Data/docker.raw.sock

• 明确绑定到 Docker Desktop，避免 OrbStack 干扰；
• 即使 OrbStack 正在运行，构建仍走 Docker Desktop 的 BuildKit + QEMU；
• 可靠支持 --platform linux/amd64 和 --load（单平台）。

dd-builder关键驱动

• docker-container 驱动：独立容器运行 BuildKit，自带 QEMU 模拟，支持跨平台构建
• dd-builder 实际使用的是 Docker Desktop 的 BuildKit 后端（即使 OrbStack 在运行）

https://docs.docker.com/build/building/multi-platform/ 官网介绍

The "classic" image store of the Docker Engine does not support multi-platform images.
Creating a custom builder that uses the docker-container driver will let you build multi-platform images.

三、构建 x86_64 镜像：docker buildx build

1、克隆GreatSQL代码

https://gitee.com/GreatSQL/GreatSQL-Docker/tree/master/GreatSQL-Build

git clone https://gitee.com/GreatSQL/GreatSQL-Docker.git

2、build  x86_64

docker buildx build \
  --platform linux/amd64 \      # ← 关键：指定目标平台
  -t greatsql/greatsql_20251216:amd64 \
  --load \                      # ← 单平台构建才支持加载到本地
  .

✅ 关键机制

QEMU 模拟交叉编译

BuildKit 自动启用 QEMU，使 RUN 指令在 x86_64 环境中执行（如 curl 下载、编译等）

镜像元数据标记为 amd64

最终镜像的 Architecture 字段为 amd64

• --load 限制
• ✅ 单平台（如仅 linux/amd64）→ 可 --load 到本地 docker images
• ❌ 多平台（linux/amd64,linux/arm64）→ 必须 --push，不能 --load

3、build 一个多架构的

docker buildx build --platform linux/amd64,linux/arm64 -t jingzhiz/greatsql_20251216:multi-architecture  --push .

注：这里需要docker login 一下，会调用到docker desktop中登录的帐户

登录docker hub查看（docker desktop 也可以）

4、最终验证命令

# ✅ 推荐：覆盖 entrypoint
docker run --platform linux/amd64 --rm --entrypoint uname greatsql/greatsql_20251216:amd64 -m

# ✅ 或显式 sh -c
docker run --platform linux/amd64 --rm greatsql/greatsql_20251216:amd64 sh -c 'uname -m'