GitHub Actions 中用 Docker 实现跨平台编译需三步对齐：先用 docker/setup-qemu-action 注册 QEMU，再用 docker/setup-buildx-action 配置多平台 builder，最后在 Dockerfile 中用 $BUILDPLATFORM/$TARGETPLATFORM 声明平台并构建推送。
在 GitHub Actions 中用 Docker 实现跨平台编译，核心是组合 Buildx + QEMU + 多平台 Dockerfile，不需要多台物理机，单个 Ubuntu runner 就能构建 linux/amd64、linux/arm64 等镜像。关键不在“能不能”，而在三处配置是否对齐：工作流驱动、QEMU 注册、Dockerfile 平台声明。
配置 Buildx 构建器并启用多平台支持
Buildx 是 Docker 官方多平台构建插件，默认不启用多平台能力，需显式创建支持目标架构的 builder：
- 使用
docker/setup-buildx-action@v3自动安装 Buildx 并初始化 builder - 通过
driver: docker-container确保使用容器驱动（兼容性好、缓存稳定） - 指定
platforms参数明确支持的架构，例如：linux/amd64,linux/arm64 - 若需自定义 builder 名称或版本，可加
name和version字段
示例步骤：
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
with:
driver: docker-container
platforms: linux/amd64,linux/arm64
注册 QEMU 用户态仿真支持
Buildx 在非原生架构上构建（如 x86 主机构建 arm64 镜像）依赖 QEMU 模拟执行。GitHub Actions 的 Ubuntu runner 默认未注册 binfmt_misc，必须提前注入：
- 调用
docker/setup-qemu-action@v3，它会自动运行tonistiigi/binfmt容器完成注册 - 该步骤必须放在
Set up Docker Buildx之前，否则 Buildx 初始化时无法识别目标平台运行时 - 无需手动
docker run --privileged，Action 已处理权限和挂载逻辑
务必保留顺序：
- name: Set up QEMU uses: docker/setup-qemu-action@v3 <ul><li>name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 with: platforms: linux/amd64,linux/arm64
编写支持多平台的 Dockerfile
普通 Dockerfile 在跨平台构建中会失败——基础镜像、编译工具链、条件判断都需适配目标架构：
- 首行用
FROM --platform=$BUILDPLATFORM显式声明构建阶段平台（避免拉取错架构 base 镜像） - 后续阶段用
FROM --platform=$TARGETPLATFORM切换目标平台（确保最终镜像元数据正确） - 用内置构建参数
TARGETARCH或TARGETVARIANT做条件分支，例如：RUN if [ "$TARGETARCH" = "arm64" ]; then apt-get install -y libssl-dev:arm64; else apt-get install -y libssl-dev:amd64; fi - Go 项目建议加
CGO_ENABLED=0避免 C 依赖架构绑定
触发构建并推送多平台镜像
Buildx 构建命令需明确指定平台列表与推送策略：
- 用
docker/build-push-action@v5替代原始docker buildx build命令，更易集成缓存与凭证 -
platforms必须与前面 builder 配置一致，且用逗号分隔（不能空格） - 开启
push: true后，Buildx 会生成 OCI Image Index（manifest list），Docker Hub 页面显示为“multi-arch” - 建议启用
cache-from和cache-to加速重复构建
典型构建步骤：
- name: Build and push
uses: docker/build-push-action@v5
with:
context: .
platforms: linux/amd64,linux/arm64
push: true
tags: user/app:latest
cache-from: type=registry,ref=user/app:buildcache
cache-to: type=registry,ref=user/app:buildcache,mode=max
