Earthly 多平台构建实战：一条命令并行构建 amd64、arm64 与 armv7 镜像

Earthly 多平台构建实战一条命令并行构建 amd64、arm64 与 armv7 镜像【免费下载链接】earthlySuper simple build framework with fast, repeatable builds and an instantly familiar syntax – like Dockerfile and Makefile had a baby.项目地址: https://gitcode.com/gh_mirrors/ea/earthly对于需要同时交付多种 CPU 架构镜像的团队来说Earthly 多平台构建是一个简单高效的选择在 Earthfile 中用一条BUILD命令加上多个--platform标志就能让 Earthly 并行构建 linux/amd64、linux/arm64 与 linux/arm/v7 三种架构的镜像并在导出时自动合并成一个多架构 manifest。本文带你从零配置到实战完成一次完整的多平台构建。为什么选择 Earthly 做多平台镜像构建Earthly 是一个轻量构建框架语法介于 Dockerfile 与 Makefile 之间写一次、到处运行。它做多平台构建有三个天然优势并行执行Earthly 自动把不同平台的构建拆成独立步骤并行运行无需手写脚本缓存复用基于 BuildKit 的分层缓存让相同步骤跨平台复用语法极简不需要docker buildx、binfmt注册脚本或 CI 矩阵配置一个 Earthfile 搞定。多平台构建前的准备配置 QEMU 模拟默认情况下构建运行在主机自身的架构上。要执行非本机的指令如 arm 平台上的RUN命令需要借助 QEMU 模拟各平台的准备工作如下运行环境需要的操作Mac / WindowsDocker Desktop 自带 QEMU开箱即用Apple Silicon (M1/M2)需在 Docker Desktop 中开启 Rosetta 模拟Linux需手动安装 QEMU 相关包CI如 GitHub Actions在 Job 中加入docker/setup-qemu-action步骤Apple Silicon 用户打开 Docker Desktop → Settings → Features in Development勾选 Use Rosetta for x86/amd64 emulationLinux 用户只需一次性执行以 Ubuntu 为例sudo apt-get install qemu-system binfmt-support qemu-user-static docker run --rm --privileged multiarch/qemu-user-static --reset -p yes docker stop earthly-buildkitd || true完整说明见官方文档 docs/guides/multi-platform.md。核心写法一条 BUILD 命令并行构建三种平台多平台构建的关键就是重复使用BUILD --platform标志。仓库自带的 examples/multiplatform/Earthfile 展示了最典型的写法VERSION 0.8 all: BUILD \ --platformlinux/amd64 \ --platformlinux/arm64 \ --platformlinux/arm/v7 \ --platformlinux/arm/v6 \ docker docker: FROM alpine:3.18 RUN uname -m CMD [uname, -m] SAVE IMAGE --push earthly/examples:multiplatformall调用一次docker目标就会同时执行四次分别在四个平台上运行uname -m也可以在命令行直接覆盖平台earthly --platformlinux/arm64 build不带任何--platform时构建按宿主机的原生架构进行。如果项目就在本仓库中克隆后可以直接体验cd examples/multiplatform earthly all自动合并多架构镜像的导出与推送一个容易困惑的问题是多个目标都SAVE IMAGE到同一个标签会互相覆盖吗不会。只要不同目标使用完全相同的镜像标签Earthly 在导出时会自动把它们合并成一个多平台multi-manifest镜像build-all-platforms: BUILD --platformlinux/amd64 --platformlinux/arm64 build build: FROM alpine:3.18 SAVE IMAGE --push org/myimage:latest执行earthly --push build-all-platforms后Docker Registry 里得到的就是一个包含 amd64 与 arm64 两个 manifest 的镜像docker pull时客户端会自动挑选匹配本机的架构。⚠️注意本地 Docker daemon 对多 manifest 镜像支持有限因此导出到本机时Earthly 会为每个架构额外生成带后缀的标签如org/myimage:latest_linux_arm64推送到 Registry 时则是单一的多架构镜像。进阶技巧交叉编译实现零模拟构建并非所有构建都必须在目标架构上执行。像 Go、Rust 这类支持交叉编译的语言可以在本机架构上编译出目标架构的二进制再放入对应平台的最终镜像——整个构建过程无需 QEMU速度更快。仓库中的 examples/multiplatform-cross-compile/Earthfile 是绝佳范例核心思路只有两行build-image: ARG TARGETPLATFORM ARG TARGETARCH ARG TARGETVARIANT FROM --platform$TARGETPLATFORM alpine:3.18 COPY \ --platformlinux/amd64 \ (build/main --GOARCH$TARGETARCH --VARIANT$TARGETVARIANT) ./example/main SAVE IMAGE --push earthly/examples:multiplatform-cross-compile要点build目标始终在linux/amd64上执行 Go 交叉编译用--GOARCH/--VARIANT控制输出架构FROM --platform$TARGETPLATFORM决定最终镜像标记的平台COPY --platformlinux/amd64 (build/main ...)从 amd64 构建产物中取二进制放进目标平台镜像build-image目标内没有任何RUN指令因此不需要模拟。善用内置平台变量让 Earthfile 更简洁Earthly 为多平台构建提供了一组开箱即用的内置参数完整列表见 docs/earthfile/builtin-args.md使用前记得先ARG声明变量示例值用途TARGETPLATFORMlinux/arm/v7当前目标构建的完整平台TARGETARCHarm目标 CPU 架构TARGETVARIANTv7目标架构变体USERPLATFORMlinux/amd64调用 earthly 命令的宿主机平台有了这些变量同一个build目标就能根据平台自动切换交叉编译参数无需为每个架构复制目标定义。常见问题与限制目前仅支持 linux 作为构建平台Windows 容器构建尚在规划中WITH DOCKER的限制包含WITH DOCKER的目标本身必须运行在宿主机原生架构上QEMU 环境暂不支持 docker-in-docker但其内部运行的镜像可以是任意架构# 正确写法build 运行在本机架构内部指定镜像的平台 build: FROM earthly/dind WITH DOCKER --pullearthly/examples:multiplatform RUN docker run --platformlinux/arm64 earthly/examples:multiplatform END构建失败排查不同平台的构建步骤相互隔离构建图DAG中任何一个分支失败都会终止整个构建日志中会清晰标注失败的分支。总结回顾一下 Earthly 多平台构建的完整路径按需配置 QEMU / Rosetta 模拟Apple Silicon 别忘了开 Rosetta用BUILD --platformlinux/amd64 --platformlinux/arm64 --platformlinux/arm/v7 target一条命令触发并行构建让各目标SAVE IMAGE到相同标签自动合并为多架构 manifest 并推送对 Go、Rust 等语言用内置变量TARGETARCH/TARGETVARIANT做交叉编译彻底摆脱模拟开销。从 examples/multiplatform 到 examples/multiplatform-cross-compile官方示例已经覆盖了最常用的两种场景照着修改即可快速接入自己的项目。【免费下载链接】earthlySuper simple build framework with fast, repeatable builds and an instantly familiar syntax – like Dockerfile and Makefile had a baby.项目地址: https://gitcode.com/gh_mirrors/ea/earthly创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考