必须换掉node-sass，改用sass（Dart Sass）——因LibSass已于2020年底终止开发，node-sass无法支持@layer、@container、color-mix()等现代CSS语法，且对错误过于宽容；迁移需彻底卸载node-sass和sass-loader，安装sass与sass-loader@^13，并清除所有残留配置。
必须换掉 node-sass，改用 sass（Dart Sass）——不是“升级”，是彻底替换，否则编译会失败或行为不可控。
为什么 node-sass 无法继续使用
LibSass 在 2020 年底终止开发，node-sass 作为其 Node.js 绑定，已失去所有语法支持能力。它无法识别 @layer、@container、color-mix()、CSS 嵌套（&:hover 写法校验）、@use 规则等现代特性；更隐蔽的问题是：它对语法错误过于宽容，比如漏写 ;、错用 & 后空格、@import 放在嵌套块里，都会被静默忽略——迁移到 Dart Sass 后，这些错误立刻暴露为编译失败。
迁移操作清单（三步清零）
残留任何 node-sass 相关代码或配置，都可能导致构建链调用错误的 implementation：
- 执行
npm uninstall node-sass sass-loader（两个都要卸载，不能只删 node-sass） - 删除
node_modules和package-lock.json，再运行npm install -D sass sass-loader@^13（sass-loader@13.3.2是 Webpack 5 最稳版本） - 全局搜索项目中所有
require('node-sass')、nodeSass:、implementation: require('node-sass')，全部删掉或替换为implementation: require('sass')
CI/CD 和本地环境常见断点
本地能跑、CI 报错，90% 是缓存或路径问题：
立即学习“前端免费学习笔记（深入）”；
- CI 脚本开头加
rm -rf node_modules package-lock.json，避免旧二进制残留 - 确认 CI 使用 Node 20+（
node-sass在 Node 20 下根本装不上） - VSCode 中如果保存不触发编译，先在终端执行
sass --version；报command not found就说明 CLI 没装或 PATH 未生效 - Webpack 用户检查
vue.config.js或webpack.config.js中是否仍有nodeSass字段；Vite 用户只需确保装了sass，无需额外配置
编译失败时优先查什么
Dart Sass 的报错不是 bug，而是原来被掩盖的语法问题浮出水面：
-
Invalid CSS after "@import"→ 全部@import必须换成@use，且@use必须在文件最顶部（不能在@media或&块内） -
Undefined variable "$xxx"→ 检查@use "path" as *是否漏写，或变量定义是否在@use语句之后 -
Invalid selector "& :hover"→ 删除&后多余空格，写成&:hover - 混用
.sass（缩进语法）和.scss？sassCLI 默认不支持前者，统一转为.scss后缀再试
真正卡住的往往不是命令执行失败，而是某处 nodeSass 字段没删干净、loader 链中某个插件覆盖了 sass-loader 输出、或者 CI 缓存了含损坏二进制的 node_modules 层。每次编译失败，先查 npm list node-sass sass 输出，看到 node-sass 就说明还没清干净。
