M1 Mac下Docker容器化Svelte应用遇esbuild平台不兼容问题

问题背景 #

在M1 Mac上将Svelte JS应用容器化到Docker时，出现esbuild平台不兼容报错。已尝试安装esbuild-wasm、在Dockerfile中添加npm i esbuild-linux-arm64、安装yarn等方法，均未解决。

当前Dockerfile内容：

FROM node:16.10.0
WORKDIR /my-website
COPY package.json .
RUN npm install
COPY . .
EXPOSE 3000
CMD ["npm", "start"]

报错信息：

You installed esbuild on another platform than the one you're currently using.
This won't work because esbuild is written with native code and needs to
install a platform-specific binary executable.

Specifically the "esbuild-darwin-arm64" package is present but this platform
needs the "esbuild-linux-arm64" package instead. People often get into this
situation by installing esbuild on Windows or macOS and copying "node_modules"
into a Docker image that runs Linux, or by copying "node_modules" between
Windows and WSL environments.

核心原因 #

M1 Mac属于darwin-arm64平台，本地安装依赖时会生成适配该平台的esbuild二进制文件。如果将包含本地node_modules的项目直接复制到Linux容器中，就会出现平台不匹配的问题。

解决方案 #

方案1：彻底隔离本地依赖，容器内完整安装 #

这是最稳妥的解决方式，避免本地依赖污染容器环境：

1. 创建.dockerignore文件，排除本地依赖目录：

node_modules
npm-debug.log
.DS_Store

2. 修改Dockerfile，先复制依赖配置文件，安装完成后再复制项目代码：

FROM node:16.10.0
WORKDIR /my-website
# 先复制package-lock.json（如果存在）和package.json
COPY package*.json ./
RUN npm install
# 复制剩余项目文件（此时不会包含本地node_modules）
COPY . .
EXPOSE 3000
CMD ["npm", "start"]

方案2：安装时强制指定目标平台 #

如果需要保留部分本地文件，可在容器内安装依赖时直接指定目标平台：

FROM node:16.10.0
WORKDIR /my-website
COPY package*.json ./
# 强制安装适配linux-arm64的依赖
RUN npm install --platform=linux --arch=arm64
COPY . .
EXPOSE 3000
CMD ["npm", "start"]

方案3：替换为跨平台的esbuild-wasm版本 #

修改项目package.json，将原生esbuild替换为wasm版本，彻底避免平台二进制依赖问题：

{
  "devDependencies": {
    "esbuild": "npm:esbuild-wasm@latest"
  }
}

修改后重新构建Docker镜像即可。

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