执行yarn start报Failed to compile，Node Sass环境不兼容如何解决

问题基础信息 #

• 运行环境：Windows 64位（内核版本10.0.22000）、Node v16.15.1
• 触发场景：React项目执行yarn start命令时SCSS编译环节失败，抛出Failed to compile错误

根因定位 #

从构建日志可确认两个核心问题：

1. 项目安装的node-sass@4.14.1版本不兼容Node 16对应的Runtime 93环境，4.x系列node-sass最高仅支持Node 14及以下版本
2. node-sass依赖的node-gyp@3.8.0版本构建时优先查找Python2环境，本地仅安装Python3.9的情况下，会因Python2/3语法差异触发语法错误，导致原生模块编译失败

解决方案 #

方案1：替换为官方维护的sass（dart-sass，优先推荐） #

node-sass已停止官方维护，目前Sass官方主推纯JS实现的dart-sass（npm包名为sass），无原生模块编译需求，不存在Node版本绑定、Python/C++构建环境依赖问题，兼容绝大多数现有SCSS语法，操作步骤：

1. 卸载旧版node-sass

yarn remove node-sass

2. 安装sass依赖

yarn add sass -D

3. 清理缓存重装依赖后启动

# Windows系统CMD/PowerShell下执行以下命令删除旧依赖和锁文件
rd /s /q node_modules
del yarn.lock
# 重新安装依赖并启动
yarn install
yarn start

若启动提示sass-loader版本不兼容，同步升级sass-loader到12.x以上版本即可，执行yarn add sass-loader@^12.0.0 -D，无需额外修改webpack配置。

方案2：保留node-sass，对齐依赖版本 #

如果因项目历史约束不能替换node-sass，可升级相关依赖到匹配Node 16的版本：

1. 升级node-sass到6.x版本（6.x系列原生支持Node 16）

yarn add node-sass@6.0.1 -D

2. 升级node-gyp到8.x版本，解决Python版本兼容问题

yarn add node-gyp@8.4.1 -D

3. 若仍报原生构建错误，以管理员权限打开PowerShell执行以下命令，自动安装Windows下Node原生模块所需的构建环境（含对应版本Python、C++编译工具）：

npm install -g windows-build-tools

4. 清理旧依赖重装后启动即可。

方案3：降级Node版本匹配旧依赖 #

如果不允许修改项目依赖版本，可将本地Node版本降级到14.x（14.21.3为14系列最终稳定版），匹配node-sass@4.14.1的版本支持范围：

1. 通过nvm-windows等Node版本管理工具切换本地Node版本到14.21.3
2. 本地安装Python2.7并添加到系统PATH环境变量
3. 删除原有node_modules文件夹，重新执行yarn install后启动项目

该方案需要额外维护多套本地开发环境，长期维护成本高，仅作为临时兜底方案。

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