迁移完成≠仅替换包，90%失败源于配置残留、@import/@use语义错配或sass-loader版本链断裂；需彻底卸载node-sass、安装兼容版sass@1.70.0与sass-loader@12.6.0、删除implementation配置、清理缓存，并重构@import为@use以适配dart-sass模块系统。
直接换 node-sass 为 sass 包，不等于迁移完成——90% 的构建失败来自配置残留、@import/@use 语义错配，或 sass-loader 版本链断裂。
确认 node-sass 是否真在项目里活着
别凭印象判断。执行这两条命令：
-
npm ls node-sass—— 若有输出，说明它还在依赖树中（哪怕没直接安装，也可能被某个 UI 库间接拉入） -
npm ls sass—— 若两者共存，sass-loader默认会优先用node-sass，除非你显式指定implementation
再搜一遍项目：全局查找 implementation: require('node-sass')、require('node-sass') 或 import nodeSass from 'node-sass'。Vue CLI 4.5+ 虽倾向 sass，但老项目常被手动锁死。
卸载 + 安装 + 清缓存，三步缺一不可
只跑 npm uninstall node-sass 是无效操作。必须同步做这三件事：
立即学习“前端免费学习笔记（深入）”；
- 卸载干净：
npm uninstall node-sass（不是--save-dev，而是彻底移除） - 装对版本：
npm install sass@1.70.0 sass-loader@12.6.0 --save-dev（sass@1.75.0+要求sass-loader@14+，而 Vue CLI 4 默认只支持到@12） - 删掉配置里的
implementation字段——现代sass-loader会自动找sass；若你非要写，只能是implementation: require('sass')，不能写成'dart-sass'（npm 包名就是sass） - 清 Webpack 缓存：
rm -rf node_modules/.cache（loader 缓存常卡住旧实现，不删它，改了配置也白搭）
@import 到 @use 不是搜索替换，是作用域重设计
@use 不是语法糖，它让变量/函数/mixin 不再自动注入全局，这是 dart-sass 模块系统的核心约束。常见报错和解法：
-
SassError: function percentage is not a function→ 改成math.percentage($val)（percentage()是 libsass 特有，dart-sass 已移入sass:math） -
can't find stylesheet to import→ 确保路径以./或../开头；@use "variables"不再等价于@import "variables"，前者要求文件存在且命名规范（如_variables.scss必须改为variables.scss或通过@forward导出） - 变量突然
undefined→ 原来靠@import“污染”全局的方式失效了，必须显式写@use "variables" as *;或@use "variables" with () -
@use "/styles/_mixins.scss"会失败（私有文件不能直接@use），应改名mixins.scss或用@forward封装导出
编译变慢？先盯住这三个配置黑洞
用了 dart-sass 还慢，大概率是这些地方踩了坑：
-
includePaths: ["node_modules"]—— 最隐蔽的 I/O 灾难，编译器会递归扫描整个node_modules查找@use目标，直接拖垮性能 -
additionalData中写@use—— 这会让每个.vue文件都触发独立模块解析，完全抵消@use的符号表复用优势 -
sourceMap: true在生产环境开启 —— 生成 sourcemap 耗时可占总编译时间 30% 以上，上线前务必关掉
真正容易被忽略的是：迁移后第一次冷启动可能仍慢——因为 @use 的模块缓存要重建，多跑两次 npm run serve 才能体现真实增量编译速度提升。
