指定linux/amd64平台构建Nuxt3 Docker镜像时进程挂起求助

在本地macOS平台构建Nuxt3应用的Docker镜像可正常完成，但使用--platform linux/amd64参数跨平台构建时，进程会在以下步骤无限挂起：

=> => # ℹ vite v4.5.0 building SSR bundle for production...
=> => # ℹ transforming...

Dockerfile采用多阶段构建流程，复制源码后在镜像内执行Nuxt构建，移除--platform参数则构建无异常。请问该问题的可能原因是什么？有哪些调试方法？

• QEMU模拟性能瓶颈：macOS（arm64架构）依赖QEMU模拟x86_64（linux/amd64）环境，Vite代码转换属于CPU密集型操作，模拟环境性能不足导致进程卡住。
• 依赖包架构不兼容：部分npm依赖包含原生二进制文件，跨平台构建时未正确下载对应linux/amd64架构的版本，引发隐性阻塞。
• Alpine镜像兼容性问题：Alpine使用musl libc，与主流glibc存在差异，在QEMU模拟环境下，Vite或Nuxt的底层操作可能触发兼容性问题，导致进程挂起。
• 构建缓存干扰：之前arm64架构的构建缓存未完全清理，跨平台构建时残留缓存导致依赖或构建状态混乱。

• 提升构建日志详细度：将Nuxt构建命令改为npx nuxt build --verbose，查看更详细的输出，定位卡住的具体模块或操作。
• 替换基础镜像：把node:21-alpine替换为node:21-bullseye（Debian基础镜像），验证是否是Alpine的musl libc导致的兼容性问题。
• 清理构建缓存：构建前执行docker builder prune -af，彻底清理所有构建缓存，避免旧缓存干扰跨平台构建。
• 单独测试Vite构建：在构建阶段单独执行npx vite build --ssr，确认是否在Vite单独构建步骤卡住，缩小问题范围。
• 强制指定依赖架构：构建前设置环境变量npm_config_platform=linux和npm_config_arch=x64，强制npm下载对应linux/amd64架构的依赖包。
• 使用buildx原始输出：执行docker buildx build --platform linux/amd64 --progress=plain .，查看更原始的构建输出，获取阻塞相关的细节信息。

# originally from https://towardsserverless.com/articles/deploying-nuxt-3-ssr-webapp-with-docker

FROM node:21-alpine as build

# update and install the latest dependencies for the alpine version
RUN apk update && apk upgrade

# set work dir as app
WORKDIR /app
# copy the nuxt project package json and package json lock if available 
COPY package* ./
# install all the project npm dependencies
RUN  npm install
# copy all other project files to working directory
COPY . ./
# build the nuxt project to generate the artifacts in .output directory
RUN npx nuxt build

# we are using multi stage build process to keep the image size as small as possible
FROM node:21-alpine
# update and install latest dependencies, add dumb-init package
# add a non root user
RUN apk update && apk upgrade && apk add dumb-init && adduser -D nuxtuser 
# set non root user
USER nuxtuser

# set work dir as app
WORKDIR /app
# copy the output directory to the /app directory from 
# build stage with proper permissions for user nuxt user
COPY --chown=nuxtuser:nuxtuser --from=build /app/.output ./
# todo: find out why this step is necessary
RUN npm install sqlite3
# expose 8080 on container
EXPOSE 8080

# set app host and port . In nuxt 3 this is based on nitro and you can read
#more on this https://nitro.unjs.io/deploy/node#environment-variables
ENV HOST=0.0.0.0 PORT=8080 NODE_ENV=production
# start the app with dumb init to spawn the Node.js runtime process
# with signal support
CMD ["dumb-init","node","/app/server/index.mjs"]

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