在arm64 GitHub Actions runner上用Docker BuildX构建armv7二进制文件时如何获取正确平台标识？

问题背景 #

之前用GitHub Actions + Docker BuildX构建多架构二进制，依赖QEMU模拟导致构建速度很慢。切换到免费的ubuntu-24.04-arm托管runner后，arm64和armv7的构建速度直接提升10倍以上，但遇到了armv7产物tar包命名错误的问题，导致无法进入工作流下一阶段。

问题原因 #

问题出在Dockerfile里用uname -m获取架构信息来命名tar包：

• 在amd64主机上构建--platform linux/arm/v7时，uname -m会正确返回armv7l
• 但在arm64主机上执行同一构建命令，uname -m返回的是aarch64，直接导致tar包命名不符合预期

可行解决方案 #

1. 用Docker BuildX内置平台变量（推荐） #

Docker BuildX在跨架构构建时会自动注入TARGETARCH和TARGETVARIANT环境变量，完全可以替代uname -m：

• 针对linux/arm/v7，TARGETARCH是arm，TARGETVARIANT是v7
• 组合这两个变量就能生成正确的架构标识，示例Dockerfile代码：

ARG TARGETARCH
ARG TARGETVARIANT
RUN ARCH="${TARGETARCH}${TARGETVARIANT:-}" \
    && tar -czf my-app-${ARCH}.tar.gz /path/to/your/binary

这种方式不管在amd64还是arm64 runner上构建，都能得到armv7的正确命名，同时保留arm64 runner的性能优势。

2. 强制指定平台执行uname（临时替代） #

如果必须保留uname -m的用法，可以在执行命令时强制指定--platform=linux/arm/v7，让Docker用QEMU模拟armv7环境执行，但会损失部分性能：

RUN --platform=linux/arm/v7 ARCH=$(uname -m) \
    && tar -czf my-app-${ARCH}.tar.gz /path/to/your/binary

3. 在Workflow中提前指定架构参数 #

在GitHub Actions的工作流里，为不同架构的构建任务直接传递明确的架构参数，避免依赖容器内命令获取：

jobs:
  build-multi-arch:
    runs-on: ubuntu-24.04-arm
    strategy:
      matrix:
        include:
          - platform: linux/arm64
            arch: aarch64
          - platform: linux/arm/v7
            arch: armv7l
    steps:
      - name: Build and package
        uses: docker/build-push-action@v5
        with:
          platforms: ${{ matrix.platform }}
          build-args: ARCH=${{ matrix.arch }}

然后在Dockerfile中直接使用传入的ARCH参数：

ARG ARCH
RUN tar -czf my-app-${ARCH}.tar.gz /path/to/your/binary

总结 #

优先选择方案1，这是Docker跨架构构建的标准做法，既可靠又能最大化利用arm64 runner的性能优势。

内容的提问来源于stack exchange，提问作者Chris Swan