Docker构建React-Vite项目yarn执行失败，报错exit code:1

本地可正常运行的React-Vite前端项目，用Docker构建时执行yarn命令失败，报错：

failed to solve: process "/bin/sh -c yarn" did not complete successfully: exit code: 1

尝试添加参数执行yarn install仍无效，错误根源是node-sass与Node v21.2.0版本不兼容导致编译失败。

原Dockerfile #

FROM node:latest

WORKDIR /usr/src/app

COPY . .

RUN yarn
RUN yarn build

EXPOSE 3000

CMD ["yarn", "start"]

关键错误日志片段 #

/root/.cache/node-gyp/21.2.0/include/node/v8-local-handle.h:253:42: error: static assertion failed: type check
  253 |     static_assert(std::is_base_of<T, S>::value, "type check");
      |                                          ^~~~~
make: *** [binding.target.mk:131: Release/obj.target/binding/src/binding.o] Error 1
gyp ERR! build error 
gyp ERR! stack Error: `make` failed with exit code: 2
...
gyp ERR! node -v v21.2.0
gyp ERR! node-gyp -v v8.4.1
gyp ERR! not ok 
Build failed with error code: 1
------
failed to solve: process "/bin/sh -c yarn" did not complete successfully: exit code: 1

1. 指定与node-sass兼容的Node版本 #

node-sass已停止维护，不同版本对应固定的Node版本范围：

• node-sass 4.x → Node 10-14
• node-sass 5.x → Node 12-16
• node-sass 6.x → Node 14-16

根据项目中node-sass的版本，修改Dockerfile使用匹配的Node镜像，比如用兼容性较好的Node 16 LTS：

FROM node:16-alpine

WORKDIR /usr/src/app

# 先拷贝依赖文件，利用Docker缓存优化构建速度
COPY package.json yarn.lock ./
RUN yarn install --frozen-lockfile

COPY . .
RUN yarn build

EXPOSE 3000

CMD ["yarn", "start"]

2. 替换node-sass为dart-sass（推荐） #

node-sass已废弃，官方推荐使用dart-sass（npm包名为sass），步骤如下：

• 卸载node-sass：yarn remove node-sass
• 安装sass：yarn add sass --dev
• 项目中无需额外修改配置，Vite等构建工具会自动识别sass替代node-sass

替换后Dockerfile可使用最新Node LTS版本，比如node:20-alpine。

3. 多阶段构建优化镜像体积（可选） #

用多阶段构建分离编译和运行环境，大幅减小最终镜像体积：

# 构建阶段：完成依赖安装和项目编译
FROM node:16-alpine AS builder
WORKDIR /app
COPY package.json yarn.lock ./
RUN yarn install --frozen-lockfile
COPY . .
RUN yarn build

# 运行阶段：用nginx托管静态文件
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

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