如何排查M1 ARM64构建linux/amd64 Docker镜像的mkdir -p错误

环境与操作 #

我在ARM64架构的Mac上使用Docker和docker-compose，执行以下命令构建linux/amd64目标镜像：

docker buildx build -f /Users/k/Desktop/project/Dockerfile \
    --platform linux/amd64 \
    --output type=docker \
    --build-arg BUILD_ENV=production \
    --build-arg NEWRELIC_LICENCE=magic \
    --pull \
    -t 2332.dkr.ecr.eu-central-1.amazonaws.com/project:prod-dfsksfdjkfdjfsdkjfsdk \
    /Users/k/Desktop/project

错误日志 #

执行后出现如下错误：

#0 building with "desktop-linux" instance using docker driver

#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 516B done
#1 DONE 0.0s

#2 [internal] load metadata for docker.io/library/node:16.4.0-stretch-slim
#2 DONE 0.9s

#3 [internal] load .dockerignore
#3 transferring context: 116B done
#3 DONE 0.0s

#4 [base 1/4] FROM docker.io/library/node:16.4.0-stretch-slim@sha256:350b89f58a40081532c5183f25f1ecb6490cf060423a99570405b0535fc8894e
#4 CACHED

#5 [internal] load build context
#5 ...

#6 [base 2/4] RUN mkdir -p /usr/src/app
#6 ERROR: process "/bin/sh -c mkdir -p /usr/src/app" did not complete successfully: exit code: 1

#5 [internal] load build context
#5 transferring context: 13.12MB 0.2s done
#5 CANCELED
------
 > [base 2/4] RUN mkdir -p /usr/src/app:
------
Dockerfile:5
--------------------
   3 |     
   4 |     # Set working directory
   5 | >>> RUN mkdir -p /usr/src/app
   6 |     WORKDIR /usr/src/app
   7 |     
--------------------
ERROR: failed to solve: process "/bin/sh -c mkdir -p /usr/src/app" did not complete successfully: exit code: 1

Dockerfile内容 #

我的Dockerfile内容如下：

# base image
FROM node:18.6.0-slim as base

# Set working directory
RUN mkdir -p /usr/src/app
WORKDIR /usr/src/app

COPY package.json yarn.lock ./

FROM base as dependencies

COPY . .
RUN yarn install
RUN yarn test
RUN yarn build
RUN rm -rf node_modules && yarn install --production

FROM base as production
COPY --from=dependencies /usr/src/app/node_modules ./node_modules
COPY --from=dependencies /usr/src/app/dist ./dist

CMD ["yarn", "start"]

项目目录/Users/k/Desktop/project下是包含package.json和yarn.lock的简单测试项目。

更新情况 #

我注释掉第5行（RUN mkdir -p /usr/src/app）后，yarn install步骤同样报错，但没有具体错误信息。Dockerfile内多数命令都以退出码1失败，且无详细调试信息，请问如何进一步排查并解决？

1. 确认QEMU跨平台模拟器配置 #

ARM64 Mac构建amd64镜像必须依赖QEMU模拟器，先验证配置：

• 执行 docker buildx inspect，检查输出中是否包含linux/amd64平台支持
• 若缺失，执行 docker run --privileged --rm tonistiigi/binfmt --install all 安装完整的QEMU支持，随后重启Docker Desktop

2. 交互式调试定位具体错误 #

直接启动临时容器手动执行命令，获取详细报错：

1. 构建基础镜像：

docker buildx build -f /Users/k/Desktop/project/Dockerfile \
    --platform linux/amd64 \
    --target base \
    --output type=docker \
    -t temp-debug-image .

2. 进入容器交互式环境：

docker run -it --platform linux/amd64 temp-debug-image /bin/sh

3. 在容器内依次执行mkdir -p /usr/src/app、yarn install等命令，观察具体错误（如权限不足、网络超时）

3. 启用命令调试日志 #

在Dockerfile的命令前添加set -x，输出执行过程细节：

RUN set -x && mkdir -p /usr/src/app
# 其他命令同理
RUN set -x && yarn install

重新构建时会打印每一步的执行细节，便于定位失败点。

4. 清理缓存解决镜像版本冲突 #

错误日志显示拉取的是node:16.4.0-stretch-slim，但Dockerfile指定的是node:18.6.0-slim，存在缓存不一致：

• 执行 docker buildx prune 清理buildx缓存
• 或在构建命令中添加--no-cache参数，强制重新拉取镜像

5. 解决权限问题 #

Node slim镜像默认使用非root用户，可能导致目录创建失败：
修改Dockerfile，临时切换root用户完成操作后再切回：

# base image
FROM node:18.6.0-slim as base

# 切换root用户创建目录并设置权限
USER root
RUN mkdir -p /usr/src/app && chown -R node:node /usr/src/app
USER node

WORKDIR /usr/src/app
COPY package.json yarn.lock ./

6. 排查网络问题 #

若yarn install失败，可能是容器网络无法访问仓库：

• 检查Docker Desktop网络设置（关闭不必要的代理）
• 在构建命令中添加--network host参数，使用主机网络进行构建

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