前阵子接手一个两年前的老后台项目CI 上第一个命令就标红。往下翻日志看到一行非常眼熟的提示npm warn deprecated node-sass4.14.1: Node Sass is no longer supported. Please usesassorsass-embeddedinstead。紧接着就是node-gyp编译失败、binding 找不到、build 直接中断。这场景在 2023 年之后的老项目里太常见了——不是代码写错了而是项目还赖在一个已经停更的 CSS 预处理器实现上。我当时的第一反应不是去修 binding而是把整个依赖链梳理了一遍然后做了一个决定把 node-sass 从项目里彻底请出去。这篇文章就是我这次迁移的完整记录包括报错出现的真实原因、为什么官方让你换到sass或sass-embedded、迁移过程中一定会遇到的 sass 编译问题、以及如何在不动业务代码的前提下让老项目重新跑起来。适合手里攥着 Vue CLI、webpack、gulp 老项目正在发愁的维护者也适合刚拿到旧仓库准备升级的开发者。1. 报错出现的四个入口以及它背后的 LibSass 退场1.1 我这次是在哪个环节翻车的先说这次的实际现场。项目在本地 Windows 上跑得好好的因为本地装的 Node 还是 14node-sass4.14.1 恰好有对应的预编译二进制但 CI 环境用的是 Node 18装依赖时就会先看到 npm 的 deprecated 警告然后在 webpack 编译阶段报出Node Sass could not find a binding for your current environment: Linux 64-bit with Node.js 18.x很多人第一反应是npm rebuild node-sass这招在早期确实能救急因为 node-sass 4.14.1 还支持通过 node-gyp 从源码编译。可现在的 CI 环境里基本没有 Python 2也没有全套 C 构建工具rebuild 大概率走到一半就挂。于是项目就卡死在这个状态。实际上这条“Node Sass is no longer supported”的提示会从四个地方冒出来npm install/npm ci时的 deprecated 警告因为 npm 仓库已经给 node-sass 整个包打上了弃用标记sass.render()或直接执行node-sassCLI 时部分版本会输出同样的提示webpack / Vue CLI / gulp 构建阶段经常以“binding 找不到”或“node-gyp rebuild failed”的形式出现CI 上换了 Node 大版本之后突然失败因为 node-sass 4.14.1 没有为新版 Node 提供预编译产物。判断是不是这个问题的办法很简单先npm ls node-sass看依赖树里有没有它再在你的本地随便写一行require(node-sass)跑一下如果看到 deprecation 提示或者 binding 报错基本就实锤了。1.2 node-sass 4.14.1 为什么会被判“不支持”node-sass 不是 Sass 语言本身它只是 LibSass 这个 C 实现的一个 Node 绑定层。LibSass 的定位是“让 Sass 编译速度快”它也确实快但它有一个致命问题Sass 官方后来把精力全部投到了 Dart Sass 上所有新语法、新函数、新模块系统都由 Dart Sass 先实现LibSass 只能慢慢追赶。2020 年 10 月Sass 官方正式宣布弃用 LibSass并给了大约两年的过渡期。从那时起LibSass 不再增加任何新功能node-sass 自然也跟着停更。node-sass4.14.1 是 4.x 分支的最后一个版本后续虽然出过 5.x、6.x、7.x、8.x、9.x但本质上还是同一个 LibSass 内核的缝缝补补解决不了根本问题。为什么说“根本问题”因为 LibSass 缺的已经不光是性能而是现代 CSS 和 Sass 的生态能力use/forward模块系统在 LibSass 里支持不完整很多项目只能继续用import新颜色函数、hwb()、color()、calc()里嵌套等新特性跟不上Node 版本兼容滞后Node 16 之后的预编译二进制基本靠社区维护安全修复也不再有保证供应链风险只能自己扛。一句话总结这个报错不是“坏了”而是“被淘汰了”。1.3 LibSass、Dart Sass 这段历史为什么值得你了解Sass 最早有 Ruby Sass后来因为性能问题出现了 C 版的 LibSass也就是 node-sass 的底层。再后来 Sass 团队决定做一个“官方参考实现”用 Dart 语言写了 Dart Sass并且在 1.0 版本之后把它默认为唯一的参考实现。Dart Sass 既可以跑在 Dart VM 上也可以编译成纯 JavaScript 供 Node 使用这就是我们现在装的sass包。node-sass之所以到现在还有大量存量项目在用主要是几个原因早期 Vue 全家桶教程默认装 node-sassCRA 早期版本也推荐 node-sass还有一堆老文章里的代码是import ~something/scss这种写法只有 node-sass 配合 webpack 才能跑通。理解这段历史你就知道迁移的本质不是“修一个报错”而是“换一个还在继续演进的编译引擎”。2. 选型对比sass 和 sass-embedded 到底差在哪2.1 三个包的实现方式和性能差异先看一张表把三个容易混淆的包放一起对比包名底层实现运行方式编译速度维护状态node-sassLibSassCNode 原生绑定快已弃用不推荐sassDart Sass 编译成纯 JS在 Node 进程内运行中等官方推荐持续更新sass-embeddedDart Sass 原生二进制通过嵌入式协议与 Node 子进程通信接近原生官方推荐持续更新node-sass的“快”是 C 带来的但它绑定平台每个 Node 版本、每个操作系统都要有对应的预编译二进制否则就得现场编译。sass是纯 JavaScript优点是不挑环境装完就能用缺点是在大型项目里编译耗时会比 node-sass 高尤其连续 watch 时能感觉出来。sass-embedded的思路是不把 Sass 编译逻辑塞进 Node 进程而是让 Node 启动一个 Dart Sass 原生可执行文件通过嵌入式协议调用这样速度上去了又不依赖特定 Node 版本的 ABI应用二进制接口。2.2 为什么我默认推荐先换 sass如果你只是想把报错压掉、让项目恢复构建我会毫不犹豫推荐sass。原因有三个第一它不需要任何原生编译npm install -D sass之后在任意 Node 版本上都能直接跑CI 不用再装 Python、build-essential、Windows Build Tools 那一堆东西。第二它是 Sass 官方维护的参考实现新语法、新特性、安全修复都会先到它这里。第三主流构建工具对它的兼容性已经非常成熟。sass-loader、gulp-sass、Next.js、Vue CLI 的接入方式都有现成文档几乎不会遇到“没人踩过”的坑。我也见过有人直接把node-sass换成sass-embedded后就报Module build failed: TypeError原因是所用 sass-loader 版本太老还不认识sass-embedded。所以稳妥的路径是先上sass把构建救活等项目稳定了再评估要不要为了性能切 sass-embedded。2.3 什么情况下值得上 sass-embedded如果你的项目满足以下任意一条可以在迁移的同时直接上 sass-embedded工程里 SCSS 文件超过几百个纯 JS 的sass编译一次要一分钟以上watch 模式频繁触发全量重编译开发体验明显卡顿用的是 monorepo多个子包共享大量 SCSS 文件构建链路是较新的 sass-loader 13/14、gulp-sass 6、Vite 5 等明确支持 embedded 协议的工具。需要注意的是sass-embedded会随包下载一个对应平台的原生二进制虽然体积比 node-sass 那套干净但在某些内网环境里第一次安装可能会因为下载源问题失败需要提前把二进制路径配好。我的建议是先在 CI 上跑通一次再说不要为了一点性能给迁移增加变量。3. 迁移实操老项目从报错到恢复构建的全过程3.1 第一步卸载依赖并按构建链路装新包这一步本身很简单但很多人只改了 package.json 忘了清 node_modules导致旧依赖残留构建还是走的旧二进制。规范做法是npm uninstall node-sass npm install -D sass rm -rf node_modules package-lock.json npm install如果用的是 yarn对应的是yarn remove node-sass yarn add -D sass rm -rf node_modules yarn.lock yarn为什么一定要删 lockfile 重新解析因为 package-lock.json 里可能还锁着 node-sass4.14.1 的整棵依赖子树也会锁着其它包对 node-sass 的依赖关系不重新解析npm 可能还会把它装回来。这里有个小细节如果你的构建工具是 gulp-sass那还要把 gulp-sass 也升到支持 dart-sass 的版本具体见下一节。不要只装sass就以为完事了工具链中间的桥接层版本不对照样会报错。3.2 第二步针对不同构建链路单独调整配置webpack 4 sass-loader 10 的老项目需要显式指定 implementation否则 sass-loader 默认还是找 node-sassnpm install -D sass-loader^10 sass然后在 webpack 配置里{ test: /\.scss$/, use: [ style-loader, css-loader, { loader: sass-loader, options: { implementation: require(sass) } } ] }webpack 5 sass-loader 13/14就省事很多sass-loader 13 之后默认实现就是sass装上sass包即可不需要额外配置。如果你想用sass-embedded需要确认 sass-loader 版本是否支持。Vue CLI 项目先确认vue/cli-service版本对应的 sass-loader。Vue CLI 4 对应 sass-loader 10Vue CLI 5 对应 sass-loader 13 左右。卸载 node-sass 后安装sass再在vue.config.js里配置module.exports { css: { loaderOptions: { sass: { additionalData: use /styles/variables.scss as *; } } } }注意additionalData里如果用了use每个样式文件都会注入一遍use只会加载一次所以不会有重复定义问题但如果原来是用import注入全局变量的改成use后要留意变量是否还要加命名空间。gulp 项目gulp-sass 5 及以上才支持 dart-sassnpm uninstall node-sass npm install -D gulp-sass5 sass然后在 gulpfile 里改一行const sass require(gulp-sass)(require(sass)); gulp.task(sass, () gulp.src(./src/**/*.scss) .pipe(sass({ style: expanded }).on(error, sass.logError)) .pipe(gulp.dest(./dist/css)) );老代码里sass({ outputStyle: compressed })这种写法在 gulp-sass 5 里对应的是sass({ style: compressed })这是我那次迁移里第一个踩到的配置差异。Next.js 项目更简单只需要安装sass包Next.js 内置的 Sass 支持会自动识别sass而不是 node-sass。next.config.js里的sassOptions继续生效不需要改代码。Angular CLI 项目Angular 12 之后内置的就是 dart-sass。如果你还卡在 Angular 11 或更早建议先升级 Angular CLI如果短期内升不了就得把 SCSS 编译单独抽出来用sass的命令行先编译成 CSS再走 Angular 的资源打包属于过渡期的“笨办法”但至少能解 CI 燃眉之急。3.3 第三步清理 lockfile 和间接依赖迁移中最容易被忽略的是“node-sass 是被别的包间接引进来的”。用这个命令看一眼npm ls node-sass如果输出里只有顶层一个node-sass4.14.1说明是项目自己直接依赖删掉就行。如果输出的依赖树里显示某个老版本的 UI 库、脚手架插件依赖了 node-sass那你不能只删顶层依赖因为你一删那个间接依赖的包在 npm install 时又会把它装回来。处理方式就两条路第一升级那个间接依赖包到新版本第二如果实在升级不了在 package.json 里用overrides强制覆盖间接依赖的 node-sass 版本。但这里要特别提醒不要直接把 node-sass 用 overrides 指向 sass因为 node-sass 和 sass 的 API 并不完全等价底层通过原生绑定调用的依赖包直接换引擎会崩。overrides 只适合把间接的 node-sass 覆盖到还兼容的 9.x 做暂时止血最终还是要靠升级依赖来解决。3.4 第四步重建验证与首批警告处理清理完依赖之后先重跑一次本地构建。这时候大概率会看到两类东西一类是真正的编译错误比如某个老语法在 dart-sass 里直接报错另一类是deprecation 警告黄色或紫色的一堆英文里带着deprecated字样。第一次跑通时不要被警告吓到先确认产物能正常生成。警告不等于错误可以先临时压掉给业务代码留出排查时间。后面第 4、5 节讲到的语法改造才是这阶段真正要处理的硬骨头。4. 代码层兼容改造最常触发 sass 编译报错的四类写法4.1 除法运算/不再是万能除号在 node-sass 里SCSS 代码写$gap / 2会被当成除法算出 8px。但在 dart-sass 的新规范里/在 CSS 中已经有了自己的含义比如font: 12px/1.5所以 Sass 不再把裸的/自动当作除法。你可能会看到这样的报错或警告Using / for division is deprecated and will be removed in Dart Sass 2.0.0. Recommendation: math.div($gap, 2)现在的正确写法是引入数学模块use sass:math; $gap: 16px; $half: math.div($gap, 2); // 8px如果是布局里需要把某个宽度按列数拆分比如老项目常见的$width: $container / $columns;统一改成math.div($container, $columns)即可。如果只是想保留 CSS 原生的斜杠写法比如font: 12px/1.5在 dart-sass 里也会尽量保留字面量但涉及到变量运算时还是明确走math.div或calc()更稳。这一点看起来小在大型老项目里往往是最大的一批报错来源因为老代码里到处是/做百分比、间距、字号换算。我的经验是先用全局搜索把.scss文件里的/运算找出来做一个正则匹配清单再分批替换。4.2import迁移到use后变量作用域为何集体失效node-sass 时代最主流的组织方式就是大量importimport variables; import mixins;迁移到 dart-sass 后直接把import改成use是最常见的错误// 这样写会让所有变量“消失” use variables; use mixins; // 原来直接用 $primary现在必须写 variables.$primary .button { color: variables.$primary; }原因很简单use引入了模块系统每个模块都有自己的命名空间。想让变量不带前缀全局可用可以这样写use variables as *; use mixins as *;但as *也有限制如果你在多个文件里定义了同名变量就会冲突而且use只能写在样式表顶部不能像import一样放在条件分支里。所以真正的迁移方案是把公共变量文件、混合宏文件改造成模块用forward统一转发入口文件用use ./styles as *;一次性引入业务组件里按需use sass:color、use sass:math等内置模块。一个更省事的过渡方案是如果项目里只有一二十个变量文件可以先use variables as *;顶着跑不用一步到位改成forward。但注意import在 dart-sass 1.x 里虽然还能用每次编译都会弹 deprecation 警告而且官方计划在 3.0 里彻底移除所以长期还是要改。4.3 颜色函数从全局函数收敛到 color 模块老项目中颜色处理几乎都会用到lighten、darken、rgba、mix这些全局函数。在 dart-sass 里它们虽然还存在但很多已经进了 deprecation 名单推荐改为sass:color模块下的新函数。旧写法新版推荐说明lighten($color, 10%)color.scale($color, $lightness: 10%)更符合感知亮度darken($color, 5%)color.adjust($color, $lightness: -5%)线性调整rgba($color, 0.5)color.change($color, $alpha: 0.5)显式修改透明度saturate($color, 20%)color.adjust($color, $saturation: 20%)调整饱和度mix($c1, $c2, 30%)color.mix($c1, $c2, 30%)颜色混合这里有个容易混淆的地方rgba($color, 0.5)在 dart-sass 里目前仍然能跑不像lighten那样明显警告。但如果你用rgba(#fff, 0.5)这种写法新版的推荐是更明确的color.change(#fff, $alpha: 0.5)或直接写 8 位十六进制#ffffff80我建议顺手一起改掉省得后续版本升级又炸一遍。颜色函数相关的警告在构建日志里通常会带上color-functions或global-builtin这种 deprecation id后面第 6 节我会讲怎么用silenceDeprecations暂时压制但尽量不要压一辈子因为颜色计算结果的差异会直接影响线上 UI。4.4 其它印象深刻的语法差异除了上面三类迁移后我还遇到过一些零散的语法差异列出来给大家排雷import ~xxx在 dart-sass 里不认识波浪线这个下一节会专门讲。早期写法rgba($color, 0.5)中的颜色变量如果来自 CSS 变量比如rgba(var(--color), 0.5)在 dart-sass 里不会报错因为它是原生 CSS 语法但要注意 Sass 不会帮你做任何颜色计算。使用for $i from 1 through 3这种老循环没有影响dart-sass 完全支持。如果有项目自定义了和内置函数重名的function在新版中会直接冲突建议改名或use内置模块后通过命名空间调用。map-get($map, key)在 node-sass 里很常见dart-sass 还能用但官方推荐map.get($map, key)如果你在日志里看到map-get的 deprecation按提示改成带命名空间的形式即可。5. 构建链路上的隐藏坑路径、缓存、文件监听5.1 “Cant find stylesheet to import”路径解析规则变了这是迁移后最经典的一个编译报错报错长这样Error: Cant find stylesheet to import. ╷ 1 │ import ~bootstrap/scss/bootstrap; │ ^^^^^^^^^^^^^^^^^^^^^^^^^^原因要从 webpack 和 sass 的职责说起。在 node-sass sass-loader 时代~前缀是 sass-loader 特供的“让 webpack 去 node_modules 里找模块”的语法但 dart-sass 本身不认识~它只会把它当成相对路径去解析。有些场景下 sass-loader 还能帮你处理~但新版本越来越倾向于让你写纯 Sass 语法所以报错就冒出来了。解决办法有两种优先推荐第二种第一种继续在 sass-loader 里配includePaths显式把 node_modules 加进去{ loader: sass-loader, options: { sassOptions: { includePaths: [path.resolve(__dirname, node_modules)] } } }然后代码里去掉~use bootstrap/scss/bootstrap;第二种既然是模块化引入更规范的做法是直接用包名定位并依靠 sass-loader 的 webpack 解析器。如果项目里~出现的位置太多也可以先用 includePaths 方案过渡再慢慢清理。5.2 波浪线~在迁移后开始失效上面说了~的问题这里单独展开因为老项目的~往往不止用在 node_modules 包上还会用在别名路径上。比如有的项目在 webpack 里配了别名指向src然后 SCSS 里写import ~/styles/mixins迁移后经常会解析失败。更隐蔽的是 CSS 里的url()。老项目可能有这种写法background: url(~/assets/logo.png);这在 node-sass css-loader 的组合下能跑通但 dart-sass 不会解析~也不会去处理 url 里的别名结果就是构建不报错图片路径在浏览器里 404。如果遇到这种情况建议把 SCSS 里的url()改成相对于当前 SCSS 文件的路径或者交给 css-loader / resolve-url-loader 处理不要在 Sass 层硬刚。5.3 watch 模式下的 inotify 与缓存问题迁移后开发环境的另一个高频问题是Linux 容器里跑npm run serve文件一多就报Error: ENOSPC: System limit for number of file watchers reached这不是 node-sass 或者 sass 的问题而是 Linux 的 inotify 文件监听上限被默认值限制住了。解决办法是临时调高sudo sysctl fs.inotify.max_user_watches524288 sudo sysctl fs.inotify.max_queued_events32768如果是 Docker 容器需要在宿主机上改并且docker run时加上--privileged或挂载相应的/proc/sys/fs/inotify。另外node-sass 时代会在项目目录生成.sass-cache文件夹迁移到sass之后这个目录不会再生成但老项目里如果残留了它记得删掉避免 IDE 或 git 误判。5.4 输出 CSS 的精度和格式差异node-sass 和 dart-sass 在输出 CSS 时的精度不一致这也是老项目迁移后大家常忽视的“隐形 bug”。比如同一段 SCSS$columns: 3; .col { width: calc(100% / 3); }或者use sass:math; .col { width: percentage(math.div(1, 3)); }node-sass 可能输出33.33333%dart-sass 会输出33.3333333333%。如果你有 CSS 快照测试、视觉回归测试这一批结果会全部“失败”不是逻辑错了而是数字精度变了。这种情况把快照重新生成一遍即可。另外node-sass 的outputStyle: compressed在 dart-sass 里对应style: compressed。sass-loader 的sassOptions.outputStyle走的是 legacy API还能兼容但直接用 dart-sass 的compileString时就要写style。这个字段名差异很不起眼却是我迁移 gulp 项目时卡得最久的一个点。6. 迁移收尾三步检查 两个保命手段6.1 扫一遍依赖树别让 node-sass 从别的包“原地复活”构建恢复后我习惯再跑一次npm ls node-sass如果输出为空说明干净了。如果还能看到 node-sass 挂在某个包下面就要回到第 3.3 节说的处理方式优先升级那个包而不是睁一只眼闭一只眼。因为只要 node-sass 还在依赖树里npm ci就会继续下载它CI 日志里那条 deprecated 警告就会一直存在某天某个安全扫描工具还会拿它的 CVE 来提醒你。还有一种情况是 package.json 里搜不到 node-sass 了但package-lock.json里还留着历史记录。删掉 lockfile 重新npm install能解决但如果团队里有多个分支在并行开发最好合并后统一提交一次 lockfile避免其他人切换分支时又把它带回来。6.2 node-sass 专属 API 和选项的替换清单如果你的项目里有人直接写了 node-sass 的 JS API比如const sass require(node-sass); sass.render({ file: src/style.scss, outFile: dist/style.css, outputStyle: compressed }, (err, result) { fs.writeFileSync(dist/style.css, result.css); });迁移到sass后最省事的方式是继续用 legacy APIrequire(sass).render也支持大部分参数名可以平移。但 legacy API 本身就是旧时代的产物dart-sass 官方已经在推动淘汰新代码建议直接上现代 APIconst sass require(sass); const result sass.compile(src/style.scss, { style: compressed, loadPaths: [node_modules] });常用参数对照node-sasssass 现代 APIsass legacy APIincludePathsloadPathsincludePathsoutputStylestyleoutputStylesourceMapsourceMap: truesourceMap: trueoutFile不需要看返回的 sourceMap 配置outFilefunctionsfunctions新机制functions如果你在 node-sass 里注册过自定义函数比如functions: { pow($base, $exp): ... }那迁移工作量会大一点因为 dart-sass 的自定义函数接口设计完全不同需要改成sass.Function相关类型。这也是我建议老项目先把编译救活、把自定义函数这种深水区放到第二步再改的原因。6.3 两个保命手段quietDeps 与 silenceDeprecations迁移过程中日志里几百条 deprecation 警告会掩盖真正的错误。dart-sass 给了两个实用的开关。第一个是quietDeps作用是压制“来自依赖包”的警告。如果警告是 node_modules 里的旧样式库通过use或import引入产生的不是你自己代码的问题那就可以在 sass-loader 配置里加上{ loader: sass-loader, options: { sassOptions: { quietDeps: true } } }这样日志会干净很多但注意它只压依赖包的警告不会压制你 src 目录下自己写的代码的警告。第二个是silenceDeprecations用来按 deprecation id 精确屏蔽某类警告。比如你暂时没时间把import全改成use可以先屏蔽 import 类警告sassOptions: { silenceDeprecations: [import, color-functions, global-builtin] }命令行下也有对应参数npx sass src/style.scss dist/style.css --quiet-deps --silence-deprecationimport,color-functions但这里要给你提个醒silenceDeprecations是“延后还债”不是“免债”。它能让你今天的构建保持绿色但群里某个同事升级 Node 或升级脚手架时债还是要还的。所以正确的节奏是先压住警告让 CI 恢复然后每周开一个半小时专门清理一个类型的 deprecation直到silenceDeprecations里什么都不用写。最后说一个我自己的心得迁移这类老项目别强求一天之内把所有语法改成新风格。项目能跑起来的优先级永远高于代码风格的完美。先把node-sass换成sass把编译错误压到零再给 deprecation 警告列一个迭代清单每周清一批。我用这个节奏处理过三个老项目没有一个是因为迁移而停摆的。很多老项目其实只改 20% 的代码就能消除 80% 的警告等真正有需求了再把import大规模换成use也不会太痛苦。