解决 Node Sass 版本不兼容问题

问题描述

在使用 create-react-app 创建 React 项目后，引入 SCSS 文件时出现编译错误：

Error: Node Sass version 5.0.0 is incompatible with ^4.0.0

这个错误通常发生在 Node.js v15+ 环境下，因为 node-sass v5.0.0 与项目中其他依赖（特别是 sass-loader）的版本要求不匹配。

根本原因

INFO

Node Sass（基于 LibSass）已于 2020 年 10 月 26 日正式被宣布弃用，官方推荐使用 Dart Sass 作为替代方案。

Node Sass v5.0.0 是一个主版本更新，与之前基于 ^4.0.0 版本约束的 sass-loader 不兼容。许多脚手架工具（如 Create React App）锁定了 sass-loader 的版本，导致版本冲突。

解决方案

方案一：迁移到 Dart Sass（推荐）

这是官方推荐的长期解决方案，Dart Sass 是 Sass 的主要实现，持续获得更新和新特性支持。

npm

npm uninstall node-sass
npm install sass --save-dev

Yarn

yarn remove node-sass
yarn add sass --dev

迁移后，你的 package.json 中应该包含：

{
  "devDependencies": {
    "sass": "^1.56.0" // 版本号可能会变化
  }
}

方案二：降级 Node Sass 版本

如果你暂时需要继续使用 Node Sass，可以降级到兼容的版本：

npm

npm uninstall node-sass
npm install node-sass@4.14.1 --save-dev

Yarn

yarn remove node-sass
yarn add node-sass@4.14.1 --dev

方案三：更新 sass-loader

如果项目配置允许，可以尝试更新 sass-loader 到兼容 Node Sass v5+ 的版本：

npm install sass-loader@^10.0.5 --save-dev

WARNING

此方案可能不适用于使用 Create React App 等预设配置的项目，因为这些工具锁定了 sass-loader 版本。

完整解决步骤

如果你选择迁移到 Dart Sass（推荐方案），请按照以下步骤操作：

1. 卸载 Node Sass

   npm uninstall node-sass

2. 安装 Dart Sass

   npm install sass --save-dev

3. 清理缓存和重新安装

   npm cache clean --force
   rm -rf node_modules package-lock.json
   npm install

4. 重新启动开发服务器

   npm start

Node.js 版本兼容性参考

如果你选择继续使用 Node Sass，请参考以下兼容性表：

Node.js 版本	兼容的 Node Sass 版本
Node 16	6.0+
Node 15	5.0+
Node 14	4.14+
Node 13	4.13+
Node 12	4.12+

注意事项

DANGER

不要手动修改 node_modules 目录中的 package.json 文件，这种修改不会被版本控制系统跟踪，且会在下次安装依赖时丢失。

• 使用 Create React App 创建的项目可能需要在 eject 后才能自定义 sass-loader 配置
• 确保所有团队成员使用相同的依赖版本，建议提交 package-lock.json 或 yarn.lock 文件

总结

Node Sass 已被官方弃用，推荐所有新项目和现有项目迁移到 Dart Sass（通过 sass 包）。这不仅能解决版本兼容性问题，还能确保获得最新的 Sass 功能和安全更新。

如果因特殊原因必须使用 Node Sass，请确保安装与你的 Node.js 版本兼容的 Node Sass 版本，并注意这是一个已弃用的解决方案。