Github Actions中构建Node.js ARM64镜像失败问题排查

我正尝试为个人Node.js项目构建可在树莓派运行的ARM64架构镜像，但在Github Actions中构建失败，报错如下：

#10 [5/5] RUN npm install
#10 0.154 exec /bin/sh: exec format error
#10 ERROR: process "/bin/sh -c npm install" did not complete successfully: exit code: 1
------
 > [5/5] RUN npm install:
0.154 exec /bin/sh: exec format error
------
Dockerfile:9
--------------------
   7 |     COPY . .
   8 |     
   9 | >>> RUN npm install
  10 |     
  11 |     EXPOSE 3000
--------------------
ERROR: failed to solve: process "/bin/sh -c npm install" did not complete successfully: exit code: 1
Error: Process completed with exit code 1.

我的Dockerfile内容如下：

FROM --platform=linux/arm64 arm64v8/node:20

WORKDIR /usr/src/app

COPY package*.json ./

COPY . .

RUN npm install

EXPOSE 3000

CMD ["node", "server.js"]

我尝试过多个Node.js版本，结果均相同；曾误使用非ARM64版本的Node镜像，构建却能成功。请问我遗漏了什么？

解决方法 #

这个错误的核心原因是：Github Actions默认运行环境是x86_64架构，直接执行ARM64架构的二进制文件（比如镜像里的/bin/sh）会因为指令集不兼容报错，必须先启用跨架构模拟或者使用多架构构建工具。

• 启用QEMU跨架构模拟
  在你的Github Actions workflow文件中，先添加QEMU的配置步骤，它会让x86_64的runner能够模拟执行ARM64的二进制指令。示例workflow代码：

  jobs:
    build-arm64-image:
      runs-on: ubuntu-latest
      steps:
        - name: 拉取代码
          uses: actions/checkout@v4
        - name: 配置QEMU
          uses: docker/setup-qemu-action@v3
        - name: 初始化Docker Buildx
          uses: docker/setup-buildx-action@v3
        - name: 构建ARM64镜像
          uses: docker/build-push-action@v5
          with:
            context: .
            platforms: linux/arm64
            push: false # 如果需要推送到镜像仓库，改为true并配置仓库凭证
  

• 为什么非ARM64镜像能成功？
  因为非ARM64的Node镜像是x86_64架构的，和Github Actions runner的架构一致，不需要模拟就能直接执行构建步骤，但这样构建出来的镜像拿到树莓派（ARM64）上运行时，会出现和现在一样的exec format error，完全无法使用。

• Dockerfile的--platform参数
  你当前使用的FROM --platform=linux/arm64 arm64v8/node:20是正确的，它明确指定了基础镜像的架构，不需要修改。

内容的提问来源于stack exchange，提问作者Morten Hagh