Node Sass 7.0.1与^4.0.0版本不兼容报错反复出现如何解决

复现报错：Error: Node Sass version 7.0.1 is incompatible with ^4.0.0

这个报错的触发逻辑是项目内使用的sass-loader版本声明仅兼容4.x系列的node-sass，但当前环境中安装的node-sass为7.0.1版本，版本校验不通过就会抛出错误。常规卸载重装、删依赖后复现问题，基本是缓存残留、隐式版本锁、全局包干扰导致的，按以下步骤操作即可解决：

操作步骤 #

• 先彻底清理本地环境，避免旧包残留干扰
  执行以下命令删除所有本地依赖、锁文件，同时清理npm缓存，防止缓存拉取旧版本错误包：

  rm -rf node_modules
  rm -f package-lock.json yarn.lock pnpm-lock.yaml
  npm cache clean --force
  

• 选择对应方案安装依赖，二选一即可
  方案1：保留原有sass-loader版本，匹配安装对应node-sass版本
  直接指定安装4.x系列稳定版node-sass，符合sass-loader的版本要求：

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

  注意：node-sass 4.x最高仅适配Node.js 14版本，本地Node版本高于14的话不要选这个方案，会报node-sass编译错误。

  方案2：替换为官方维护的dart-sass（长期推荐方案）
  node-sass已经官方废弃停止维护，版本和Node.js强绑定很容易出兼容问题，直接替换为dart-sass（包名为sass）不需要修改任何业务sass代码，可适配所有版本的sass-loader：

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

• 残留问题排查
  执行完上述操作仍报错的话，逐一检查以下配置项：

  • 检查package.json中的resolutions字段，若存在强制锁定node-sass为7.0.1的配置，删除该条规则或修改为匹配版本
  • 检查全局npm包，若全局安装了7.0.1版本的node-sass，部分脚手架会优先读取全局包，执行npm uninstall node-sass -g移除全局版本即可
  • 检查项目npm源配置，若使用私有源存在包缓存同步问题，切换到官方源重新执行安装即可

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