使用buildx构建多架构Docker镜像时arm64镜像无法运行的问题

问题描述 #

使用buildx构建多架构Docker镜像（包含linux/arm64、linux/amd64、linux/arm），构建流程无报错，但在树莓派（arm64架构）运行镜像时出现错误：
exec /usr/local/bin/docker-entrypoint.sh: exec format error
单独指定--platform linux/arm64构建的镜像可正常运行，已确认buildx的qemu依赖配置正常。

使用的构建命令：

docker buildx build --platform linux/arm64,linux/amd64,linux/arm -t z0pyrus/photon-reddit:latest . --push

原Dockerfile内容：

ARG TARGETARCH
FROM ${TARGETARCH}/node as build-env
ENV BUILDX_ARCH="${TARGETOS:-linux}-${TARGETARCH}"

WORKDIR /app

COPY . .

RUN npm install && npm audit fix

CMD [ "npm", "run", "build-and-start" ]
EXPOSE 8080 3306

问题原因 #

官方Node.js镜像本身就是多架构镜像，无需在FROM指令前添加${TARGETARCH}/前缀。当你写FROM ${TARGETARCH}/node时，实际拉取的是arm64/node、amd64/node这类非官方单架构镜像（或命名空间错误的镜像），这类镜像内的docker-entrypoint.sh依赖的二进制文件可能是x86架构的，导致在arm64设备上执行时出现格式不兼容问题。

而单独指定--platform linux/arm64构建时，本地环境刚好匹配架构，能拉取到正确的镜像；但多架构构建时，buildx无法正确处理这种自定义架构前缀的镜像，最终生成的arm64镜像内部包含不兼容的二进制内容。

解决方案 #

修改Dockerfile的FROM行，直接使用官方Node.js镜像，去掉${TARGETARCH}/前缀：

ARG TARGETPLATFORM
FROM node as build-env
ENV BUILDX_ARCH="${TARGETPLATFORM}"

WORKDIR /app

COPY . .

RUN npm install && npm audit fix

CMD [ "npm", "run", "build-and-start" ]
EXPOSE 8080 3306

额外说明 #

• 官方多架构镜像会自动根据TARGETPLATFORM（或TARGETARCH）拉取对应架构的镜像，buildx跨架构构建时会通过qemu模拟目标环境，确保镜像适配目标架构。
• 使用TARGETPLATFORM作为环境变量值更准确，它包含完整的os/arch信息（如linux/arm64），和构建时指定的--platform参数格式一致。
• 修改后重新执行原buildx构建命令即可，生成的多架构镜像在arm64、amd64等设备上均可正常运行。

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