直接换用 sass（Dart Sass）是唯一可靠解法；所有编译报错几乎都源于残留、混用或配置硬编码，而非语法本身写错，常见原因包括构建配置中显式引用 node-sass、@import 未转为 @use、嵌套和变量作用域变严格、CI/CD 环境残留及平台差异。
直接换掉 node-sass，用 sass（Dart Sass）是唯一可靠解法；所有编译报错几乎都源于残留、混用或配置硬编码，而非语法本身写错。
为什么卸载 node-sass 后还报 “cannot find module 'node-sass'”
这不是没卸干净，而是构建链里某处仍显式引用了它。常见位置包括：
-
vue.config.js里的css.loaderOptions.sass.implementation字段写死了require('node-sass') -
vite.config.ts中css.preprocessorOptions.sass配置了implementation: require('node-sass') - 某些旧版 UI 库的插件（如
ant-design-vue的 style 插件）内部硬依赖node-sass -
package-lock.json或node_modules缓存未清，导致sass-loader初始化时仍尝试加载旧 binding
执行 npm ls node-sass 和 npm ls sass 双查，只要前者有输出，就说明没清完；后者必须出现在 devDependencies 下才有效。
@import 突然失效：Dart Sass 强制要求 @use
@import 在 Dart Sass 中已被标记为 deprecated，且自 v1.70.0 起不再支持路径解析松散模式——漏分号、别名未展开、嵌套中使用，全都会报错。
立即学习“前端免费学习笔记（深入）”；
- 把
@import "vars";改成@use "vars" as *;，且必须放在文件最顶部（不能在@media或嵌套块内） - 若原
@import路径含@/styles/xxx别名，需确认该别名在构建配置中已注册；否则改用相对路径或统一入口@use "@/styles/index.scss" as *; - 全局注入（如
additionalData）里不能再拼接多条@import，必须合并进一个 SCSS 入口文件再@use
错误示例：file to import not found or unreadable: variables，大概率是路径没转 @use + 别名未生效。
SCSS 嵌套和变量报错：不是语法错，是作用域变严格了
Node Sass（LibSass）会悄悄忽略很多嵌套不合法、变量未声明、& 后空格等错误；Dart Sass 一并暴露出来，本质是修复“伪正常”。
-
& :hover→ 必须写成&:hover（&和伪类间不能有空格） - 嵌套中引用
$color-primary报Undefined variable→ 检查是否漏了@use "path/to/vars" as *;，或变量定义在@use之后 -
Invalid CSS after "&"→ 多半是缩进不一致（混用空格/Tab）、嵌套块内写了{后换行、或@at-root使用位置非法 - 除法
width: 100px / 2报 warning → 改用@use "sass:math"; width: math.div(100px, 2);
注意：sass 包默认不支持 .sass（缩进语法），只认 .scss；混用项目务必先统一后缀。
CI/CD 构建失败或本地能跑线上炸：缓存和平台差异最易被忽略
本地 OK 但 CI 报错，90% 是环境残留或平台特性没对齐：
- GitHub Actions / GitLab CI 默认不会自动清理
node_modules，必须显式加rm -rf node_modules package-lock.json步骤 - Mac M1/M2 用户装过
node-sass，node_modules里可能残留darwin-arm64binding，干扰sass自动发现 - HBuilderX 4.56+ 的 uni-app（vue2）项目默认走
dart-sass，但若manifest.json里写了"sassImplementationName": "node-sass"，会强制回退——删掉这行 - Vite 项目若用了
sass-embedded（Windows 常见），要确认node_modules/sass-embedded-win32-x64/dart-sass.exe存在且可执行
真正卡住的往往不是命令执行失败，而是某台机器上 package-lock.json 锁着旧版 sass-loader，或者某处配置里藏着一行 implementation: require('node-sass')，连搜都搜不到——得 grep 全局代码和依赖源码。
