Vite+React+SCSS报错：找不到Embedded Dart Sass编译器可执行文件

问题根源 #

你本地Windows环境安装的sass-embedded依赖是Windows版本，但Docker容器运行的是Linux环境。若直接将本地node_modules挂载进容器，容器会找不到适配Linux的sass-embedded-linux-musl-x64可执行文件，从而抛出错误。

具体修复方案 #

方案1：在Docker容器内安装依赖（推荐） #

避免挂载本地node_modules，直接在Dockerfile中执行依赖安装，确保依赖适配容器的Linux环境：

1. 调整Dockerfile内容：

FROM node:20-alpine
WORKDIR /app

# 优先复制依赖配置文件，利用Docker缓存优化构建速度
COPY package*.json ./
RUN npm install

COPY . .

EXPOSE 5173
CMD ["npm", "run", "dev"]

2. 构建并启动容器：

docker build -t vite-react-scss .
docker run -p 5173:5173 vite-react-scss

方案2：挂载代码时隔离本地node_modules #

若需要本地代码实时同步到容器，可通过Docker匿名卷隔离本地node_modules，让容器单独维护适配自身环境的依赖：
创建docker-compose.yml：

version: '3'
services:
  vite-app:
    image: node:20-alpine
    working_dir: /app
    ports:
      - "5173:5173"
    volumes:
      - ./:/app
      - /app/node_modules  # 用匿名卷覆盖本地node_modules目录
    command: sh -c "npm install && npm run dev"

启动容器后，会自动安装Linux适配版依赖，本地代码修改可实时同步到容器。

方案3：切换为传统Sass编译API #

若暂时不想调整Docker配置，可修改Vite配置使用传统Sass API，放弃sass-embedded：

1. 修改vite.config.ts：

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        api: 'legacy', // 替换为传统编译API
      }
    }
  }
})

2. 替换依赖包：

npm uninstall sass-embedded
npm install sass --save-dev

验证步骤 #

1. 删除本地node_modules和package-lock.json，清除缓存
2. 按照上述任一方案重新构建或启动容器
3. 启动项目后检查SCSS是否能正常编译

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