Docker buildx 多架构镜像实战:一次构建 amd64arm64,告别 exec format error你在 M 系列 Mac(arm64)上docker build打了个镜像,推到仓库,部署到云上的 x86 服务器(amd64),容器起不来,日志一行:exec /app: exec format error或者反过来:在 x86 CI 上构建的镜像,拉到树莓派、arm 云主机上跑不了。根因是镜像里的二进制是按构建机的 CPU 架构编译的,架构不匹配,内核根本没法执行。解法不是给每个架构各建一个仓库,而是用docker buildx一次构建出多架构镜像,推成一个 manifest list。用户docker pull同一个 tag,Docker 会自动挑对应自己 CPU 架构的那份。这篇手把手把它跑通。先理解:为什么普通 build 是单架构的docker build默认只为当前机器的架构构建。你可以查镜像的架构:dockerinspect--format{{.Architecture}}myapp:latest# arm64 ← 在 M1 Mac 上就是这个推上去后,x86 服务器拉下来,架构对不上,exec format error。你或许试过在服务器上加--platform:dockerrun--platformlinux/amd64 myapp:latest# 靠 QEMU 模拟,能跑但巨慢模拟能应急,但性能差、也不该用在生产。真正的解法是构建期就把两个架构都产出来。一次性准备:开启 buildx 和 QEMUbuildx是 Docker 官方的增强构建器,基于 BuildKit,新版 Docker Desktop / Docker Engine 已自带。要在一台机器上构建非本机架构的镜像,得靠 QEMU 做跨架构模拟编译。先注册 QEMU:# 注册 binfmt handlers,让本机能模拟执行其它架构的二进制dockerrun--privileged--rmtonistiigi/binfmt--installall然后创建一个支持多架构的 builder 实例(默认的 builder 不支持多平台输出):# 创建并切换到一个新的 builderdockerbuildx create--namemultiarch--driverdocker-container--use# 启动并查看它支持哪些平台dockerbuildx inspect--bootstrapinspect输出里Platforms:那行应该能看到linux/amd64, linux/arm64, linux/arm/v7 ...。看到 amd64 和 arm64 就够了。这里有个关键点:--driver docker-container。默认的dockerdriver不支持多平台构建,必须用docker-container驱动(它跑一个独立的 BuildKit 容器)。很多人第一次卡在构建报错说不支持多 platform,就是因为没换 driver。核心命令:一条命令建两个架构并推送dockerbuildx build\--platformlinux/amd64,linux/arm64\-tregistry.example.com/myapp:1.0.0\--push\.三个关键参数:--platform linux/amd64,linux/arm64:一次构建这两个架构。--push:构建完直接推到仓库。多架构构建必须直接 push,不能只--load到本地——因为本地 Docker 镜像存储没法存一个 tag 对应多架构的 manifest list,只有仓库能存。这是第二个高频坑:多平台构建加--load会报错,必须--push(或--output到 tar)。结尾的.:构建上下文。推完后验证一下 manifest,确认两个架构都在:dockerbuildx imagetools inspect registry.example.com/myapp:1.0.0输出会列出一个 manifest list,底下挂着platform: linux/amd64和platform: linux/arm64两个子 manifest。之后不管是 x86 服务器还是 arm 机器,docker pull registry.example.com/myapp:1.0.0都会自动拉对的那份,exec format error彻底消失。Dockerfile 要注意的:别把架构写死多架构构建对 Dockerfile 有要求——凡是下载某架构专属二进制的地方,都不能写死架构。BuildKit 会自动注入几个构建参数,用它们:# syntaxdocker/dockerfile:1 FROM --platform$BUILDPLATFORM golang:1.22 AS builder # BuildKit 自动提供这些 ARG,声明后即可使用 ARG TARGETOS ARG TARGETARCH WORKDIR /src COPY . . # 关键:用 TARGETOS/TARGETARCH 交叉编译出目标架构的二进制 # 这样构建在 amd64 机器上、也能产出 arm64 的可执行文件,不走 QEMU 更快 RUN CGO_ENABLED0 GOOS$TARGETOS GOARCH$TARGETARCH go build -o /app . FROM alpine:3.20 COPY --frombuilder /app /app ENTRYPOINT [/app]几个要点:$BUILDPLATFORM是构建机的架构,$TARGETPLATFORM/$TARGETOS/$TARGETARCH是目标架构。FROM --platform$BUILDPLATFORM让 builder 阶段始终跑在本机架构上(快),再靠 Go 的交叉编译产出目标架构二进制。这比让 QEMU 模拟整个编译过程快得多。ARG TARGETOS/ARG TARGETARCH必须显式声明才能在RUN里用,否则是空值。如果你下载的是预编译工具(比如 kubectl、某个 CLI),记得用$TARGETARCH拼下载 URL,别写死amd64:ARG TARGETARCH RUN curl -fsSL https://example.com/tool-linux-${TARGETARCH} -o /usr/local/bin/tool \ chmod x /usr/local/bin/tool对非 Go 项目(Node、Python 等解释型),通常不涉及交叉编译,直接--platform多架构构建、让基础镜像自己按架构拉对应版本即可,更省心。放进 CI:GitHub Actions 示例日常最实用的是让 CI 自动出多架构镜像。官方 action 已经把 QEMU、buildx 都封装好了:name:build-and-pushon:push:tags:[v*]jobs:docker:runs-on:ubuntu-lateststeps:-uses:actions/checkoutv4-name:Set up QEMUuses:docker/setup-qemu-actionv3-name:Set up Buildxuses:docker/setup-buildx-actionv3-name:Login to registryuses:docker/login-actionv3with:registry:registry.example.comusername:${{secrets.REGISTRY_USER}}password:${{secrets.REGISTRY_PASSWORD}}-name:Build and push multi-archuses:docker/build-push-actionv6with:context:.platforms:linux/amd64,linux/arm64push:truetags:registry.example.com/myapp:${{github.ref_name}}cache-from:typegha# 用 GitHub Actions 缓存加速cache-to:typegha,modemaxcache-from/cache-to: typegha会把 BuildKit 层缓存存进 GitHub Actions 缓存,第二次构建能省掉没变的层,多架构构建本来慢,这个缓存很关键。小结exec format error的根因是镜像架构和运行机器的 CPU 架构不匹配;解法是构建成多架构镜像(manifest list),让docker pull自动选对架构。准备工作:binfmt注册 QEMU docker buildx create --driver docker-container --use(默认dockerdriver 不支持多平台)。构建命令:docker buildx build --platform linux/amd64,linux/arm64 -t ... --push .。多架构必须--push,不能--load(本地存储存不下 manifest list)。Dockerfile 里用$BUILDPLATFORM$TARGETOS/$TARGETARCH交叉编译,别把架构写死;下载预编译二进制时用$TARGETARCH拼 URL。CI 用官方setup-qemu-actionbuild-push-action,配cache-from/to: typegha提速。一句话记住:用 buildx 一次产出多架构、推成一个 tag,让每台机器各取所需——这才是彻底根治exec format error的正道。
Docker buildx 多架构镜像实战:一次构建 amd64arm64,告别 exec format error你在 M 系列 Mac(arm64)上docker build打了个镜像,推到仓库,部署到云上的 x86 服务器(amd64),容器起不来,日志一行:exec /app: exec format error或者反过来:在 x86 CI 上构建的镜像,拉到树莓派、arm 云主机上跑不了。根因是镜像里的二进制是按构建机的 CPU 架构编译的,架构不匹配,内核根本没法执行。解法不是给每个架构各建一个仓库,而是用docker buildx一次构建出多架构镜像,推成一个 manifest list。用户docker pull同一个 tag,Docker 会自动挑对应自己 CPU 架构的那份。这篇手把手把它跑通。先理解:为什么普通 build 是单架构的docker build默认只为当前机器的架构构建。你可以查镜像的架构:dockerinspect--format{{.Architecture}}myapp:latest# arm64 ← 在 M1 Mac 上就是这个推上去后,x86 服务器拉下来,架构对不上,exec format error。你或许试过在服务器上加--platform:dockerrun--platformlinux/amd64 myapp:latest# 靠 QEMU 模拟,能跑但巨慢模拟能应急,但性能差、也不该用在生产。真正的解法是构建期就把两个架构都产出来。一次性准备:开启 buildx 和 QEMUbuildx是 Docker 官方的增强构建器,基于 BuildKit,新版 Docker Desktop / Docker Engine 已自带。要在一台机器上构建非本机架构的镜像,得靠 QEMU 做跨架构模拟编译。先注册 QEMU:# 注册 binfmt handlers,让本机能模拟执行其它架构的二进制dockerrun--privileged--rmtonistiigi/binfmt--installall然后创建一个支持多架构的 builder 实例(默认的 builder 不支持多平台输出):# 创建并切换到一个新的 builderdockerbuildx create--namemultiarch--driverdocker-container--use# 启动并查看它支持哪些平台dockerbuildx inspect--bootstrapinspect输出里Platforms:那行应该能看到linux/amd64, linux/arm64, linux/arm/v7 ...。看到 amd64 和 arm64 就够了。这里有个关键点:--driver docker-container。默认的dockerdriver不支持多平台构建,必须用docker-container驱动(它跑一个独立的 BuildKit 容器)。很多人第一次卡在构建报错说不支持多 platform,就是因为没换 driver。核心命令:一条命令建两个架构并推送dockerbuildx build\--platformlinux/amd64,linux/arm64\-tregistry.example.com/myapp:1.0.0\--push\.三个关键参数:--platform linux/amd64,linux/arm64:一次构建这两个架构。--push:构建完直接推到仓库。多架构构建必须直接 push,不能只--load到本地——因为本地 Docker 镜像存储没法存一个 tag 对应多架构的 manifest list,只有仓库能存。这是第二个高频坑:多平台构建加--load会报错,必须--push(或--output到 tar)。结尾的.:构建上下文。推完后验证一下 manifest,确认两个架构都在:dockerbuildx imagetools inspect registry.example.com/myapp:1.0.0输出会列出一个 manifest list,底下挂着platform: linux/amd64和platform: linux/arm64两个子 manifest。之后不管是 x86 服务器还是 arm 机器,docker pull registry.example.com/myapp:1.0.0都会自动拉对的那份,exec format error彻底消失。Dockerfile 要注意的:别把架构写死多架构构建对 Dockerfile 有要求——凡是下载某架构专属二进制的地方,都不能写死架构。BuildKit 会自动注入几个构建参数,用它们:# syntaxdocker/dockerfile:1 FROM --platform$BUILDPLATFORM golang:1.22 AS builder # BuildKit 自动提供这些 ARG,声明后即可使用 ARG TARGETOS ARG TARGETARCH WORKDIR /src COPY . . # 关键:用 TARGETOS/TARGETARCH 交叉编译出目标架构的二进制 # 这样构建在 amd64 机器上、也能产出 arm64 的可执行文件,不走 QEMU 更快 RUN CGO_ENABLED0 GOOS$TARGETOS GOARCH$TARGETARCH go build -o /app . FROM alpine:3.20 COPY --frombuilder /app /app ENTRYPOINT [/app]几个要点:$BUILDPLATFORM是构建机的架构,$TARGETPLATFORM/$TARGETOS/$TARGETARCH是目标架构。FROM --platform$BUILDPLATFORM让 builder 阶段始终跑在本机架构上(快),再靠 Go 的交叉编译产出目标架构二进制。这比让 QEMU 模拟整个编译过程快得多。ARG TARGETOS/ARG TARGETARCH必须显式声明才能在RUN里用,否则是空值。如果你下载的是预编译工具(比如 kubectl、某个 CLI),记得用$TARGETARCH拼下载 URL,别写死amd64:ARG TARGETARCH RUN curl -fsSL https://example.com/tool-linux-${TARGETARCH} -o /usr/local/bin/tool \ chmod x /usr/local/bin/tool对非 Go 项目(Node、Python 等解释型),通常不涉及交叉编译,直接--platform多架构构建、让基础镜像自己按架构拉对应版本即可,更省心。放进 CI:GitHub Actions 示例日常最实用的是让 CI 自动出多架构镜像。官方 action 已经把 QEMU、buildx 都封装好了:name:build-and-pushon:push:tags:[v*]jobs:docker:runs-on:ubuntu-lateststeps:-uses:actions/checkoutv4-name:Set up QEMUuses:docker/setup-qemu-actionv3-name:Set up Buildxuses:docker/setup-buildx-actionv3-name:Login to registryuses:docker/login-actionv3with:registry:registry.example.comusername:${{secrets.REGISTRY_USER}}password:${{secrets.REGISTRY_PASSWORD}}-name:Build and push multi-archuses:docker/build-push-actionv6with:context:.platforms:linux/amd64,linux/arm64push:truetags:registry.example.com/myapp:${{github.ref_name}}cache-from:typegha# 用 GitHub Actions 缓存加速cache-to:typegha,modemaxcache-from/cache-to: typegha会把 BuildKit 层缓存存进 GitHub Actions 缓存,第二次构建能省掉没变的层,多架构构建本来慢,这个缓存很关键。小结exec format error的根因是镜像架构和运行机器的 CPU 架构不匹配;解法是构建成多架构镜像(manifest list),让docker pull自动选对架构。准备工作:binfmt注册 QEMU docker buildx create --driver docker-container --use(默认dockerdriver 不支持多平台)。构建命令:docker buildx build --platform linux/amd64,linux/arm64 -t ... --push .。多架构必须--push,不能--load(本地存储存不下 manifest list)。Dockerfile 里用$BUILDPLATFORM$TARGETOS/$TARGETARCH交叉编译,别把架构写死;下载预编译二进制时用$TARGETARCH拼 URL。CI 用官方setup-qemu-actionbuild-push-action,配cache-from/to: typegha提速。一句话记住:用 buildx 一次产出多架构、推成一个 tag,让每台机器各取所需——这才是彻底根治exec format error的正道。
