node-sass 停止维护！老项目迁移 Dart Sass 完整教程

一、什么是 node-sass？还在更新吗？

node-sass 是 LibSass（C++实现的Sass编译器） 在Node.js中的包装器，作用是把.scss/.sass文件编译成CSS，在Vue、React Webpack项目中通常搭配sass-loader使用。

⚠️ 重要：node-sass 已经正式EOL（生命周期结束，停止维护）

2020年官方标记 LibSass / node-sass 为废弃，不再新增任何Sass新语法特性；
2024-07-24 Sass官方博客正式宣布 node-sass 彻底退休，GitHub仓库归档，不再发布新版本，npm包标记deprecated；
最后一个正式版本node-sass@9.0.0发布于2023年，后续无更新；底层LibSass在2025.10也到达EOL。

痛点：node-sass需要下载和Node版本匹配的二进制包，安装极其容易失败，经常需要node-gyp、Python编译环境，Node版本升级直接项目打包报错。

✅ 新项目禁止使用node-sass，所有老项目建议迁移到 Dart Sass（npm包名：sass）

二、node-sass 和 Dart Sass 核心区别

Dart Sass是Sass官方用Dart语言开发，编译为纯JS发布，是官方唯一持续维护 的Sass编译器，npm包名字直接叫sass（不要装dart-sass，该包已废弃）。

对比项	node-sass	Dart Sass（包名：sass）
底层实现	C++ LibSass，Node原生绑定	Dart编写，打包纯JS，无原生依赖
维护状态	仓库归档，EOL停止维护	持续迭代，官方主力推荐
安装特点	需要匹配Node二进制包，node-gyp编译坑多	纯JS包，任意Node版本均可安装，无编译依赖
语法支持	仅支持旧`@import`，不支持`@use`、`@forward`等新特性	完整支持最新Sass规范，模块化`@use`、内置函数全部支持
性能	C++原生，编译略快；现代项目差距感知很小	JS实现稍慢，大部分业务项目几乎无感知
打包工具	老版webpack sass-loader配套	sass-loader、Vite、Rollup原生支持
API	旧版回调render API	兼容旧API，新增modern现代API，旧API未来会移除

语法行为差异（迁移高频坑）

导入规则

node-sass只有@import，重复导入会重复加载变量，全局命名空间污染；

Dart Sass推荐@use模块化，变量自带命名空间；@import已经标记废弃。
Vue深度选择器（高频报错）

node-sass支持 /deep/；Dart Sass不再识别 /deep/，需要替换为::v-deep（Vue2）或:deep()（Vue3推荐）。
除法 / 警告

node-sass直接把/当成除法；Dart Sass区分：calc()内部的/正常；普通变量除法会触发警告。

scss 复制代码

// Dart Sass推荐写法
@use "sass:math";
$w: math.div(100, 2);

ElementUI老项目大量该警告，警告不影响打包，可临时忽略。

@extend 语法限制

node-sass允许复杂选择器@extend；Dart Sass严格规范，仅支持简单选择器，复杂写法直接报错，需要重构。
CSS变量 var()

node-sass会解析var内部内容；Dart Sass原样保留CSS变量，更符合CSS标准，极少数老项目样式行为变化。

三、完整迁移步骤（Webpack/Vue项目通用）

步骤1：替换依赖包

bash 复制代码

# 卸载node-sass
npm uninstall node-sass -D

# 安装 Dart Sass（包名是sass）
npm install sass -D

重点：sass-loader不需要卸载重装 ，新版sass-loader会自动优先加载sass。

如果sass-loader版本 < 8.x，硬依赖node-sass，需要升级sass-loader：

bash 复制代码

npm install sass-loader@^10 -D

步骤2：webpack配置（绝大多数项目不用改！）

极少数老项目需要手动指定implementation，在sass-loader配置增加：

js 复制代码

{
  loader: 'sass-loader',
  options: {
    implementation: require('sass') // 显式指定使用dart sass
  }
}

步骤3：批量修复scss语法

Vue项目全局搜索替换 /deep/ → ::v-deep 或 :deep()
除法警告：可使用官方sass-migrator批量自动修复

sass-migrator 官方迁移工具，自动修复除法、废弃语法，适合中大型项目

bash 复制代码

# 全局安装迁移工具
npm install -g sass-migrator

# 预览修改（dry-run不会改动源文件）
sass-migrator division src/**/*.scss --dry-run

# 执行批量替换除法语法
sass-migrator division src/**/*.scss

步骤4：启动项目验证

bash 复制代码

npm run dev
npm run build

检查页面样式是否丢失、编译报错，重点关注深度选择器、尺寸计算、主题变量。

四、常见报错&解决方案

Cannot find module "node-sass"

原因：sass-loader版本过低；解决方案：升级sass-loader到10及以上版本

SyntaxError: expected selector. /deep/

原因：Dart Sass不支持/deep/；解决方案：全局替换/deep/为::v-deep / :deep()

Deprecation Warning: Using / for division

除法废弃警告，不影响打包运行；方案：sass-migrator批量修复，或临时锁定sass版本。

Undefined variable 变量找不到

Dart Sass导入路径大小写更严格；检查@import相对路径，长期建议逐步迁移@use模块化写法。

五、老项目稳定版本推荐（Vue2后台项目，如vue-admin-template）

json 复制代码

"devDependencies": {
  "sass": "~1.32.6",
  "sass-loader": "^10.2.1"
}

锁定sass低版本，规避大量除法警告，保证业务优先跑通，后续再分批清理废弃语法。

六、迁移策略建议

小型项目 ：替换依赖包 → 全局替换/deep/ → 启动测试；
中大型老后台项目
- 第一步：锁定sass稳定版本，保证项目先跑通；
- 第二步：利用sass-migrator分批清理废弃语法；
- 长期：逐步把@import改造为@use模块化写法；
新项目 ：直接使用sass(Dart Sass)，优先@use语法，不再使用node-sass。

七、总结

node-sass已经彻底停止维护，随着Node版本升级，安装失败问题会越来越频繁，迁移Dart Sass是唯一长期可行方案 。

迁移大部分工作只需要替换依赖包，主要工作量集中在修复少量不兼容的scss语法，Vue项目重点处理深度选择器，老ElementUI项目注意除法警告即可。