升级Node版本后npm install失败，v16.14.0环境下无法安装Sass

核心根因 #

这类报错基本由四类问题触发：

• 项目依赖的老版本node-sass和Node 16版本不兼容，node-sass属于原生扩展包，版本和Node版本强绑定，版本不匹配时会直接触发编译失败
• 升级Node后没有清理旧依赖缓存，残留的旧版本编译产物和新Node环境冲突
• 网络原因导致Sass依赖的预编译二进制包拉取失败
• 本地缺少原生包编译需要的基础环境

按优先级排查解决 #

1. 优先替换为无原生依赖的官方Sass实现 #

node-sass已经官方废弃，目前官方默认维护的是纯JS实现的sass（原dart-sass），没有原生编译步骤，完全不存在版本绑定、环境依赖问题，是成本最低的解决方式：
执行以下命令替换依赖：

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

绝大多数项目替换后不需要修改业务代码，Sass语法完全兼容，替换完成直接重新执行npm install即可。
如果项目因为历史原因必须使用node-sass，请将版本升级到适配Node 16的6.0.1及以上版本，执行：

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

2. 彻底清理残留依赖与缓存 #

升级Node版本后必须清理旧环境的残留文件，否则会持续出现兼容性报错，按顺序执行命令：

• 删除现有依赖目录和版本锁文件
  Windows环境执行：

  rmdir /s /q node_modules
  del package-lock.json
  

  Mac/Linux环境执行：

  rm -rf node_modules
  rm package-lock.json
  

• 清理npm本地缓存

  npm cache clean --force
  

• 重新执行安装命令

  npm install
  

3. 配置国内镜像解决二进制包下载失败 #

Sass安装时需要拉取对应平台的预编译二进制文件，国内网络环境下经常出现拉取超时失败，安装前先执行配置命令，将二进制包源切换为国内镜像：

npm config set sass_binary_site https://npmmirror.com/mirrors/node-sass/

如果使用的是纯JS版sass，对应配置为：

npm config set sass_binary_site https://npmmirror.com/mirrors/dart-sass/

配置完成后再重新执行安装即可。

4. 补全本地编译环境 #

如果以上步骤操作后仍然走源码编译流程报错，说明本地缺少原生扩展编译需要的基础环境：

• Windows系统：以管理员身份运行终端，执行npm install --global --production windows-build-tools安装编译依赖，安装完成后重启终端再重装依赖
• Mac系统：终端执行xcode-select --install按照提示安装Xcode命令行工具，完成后再重装依赖

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