必须更换为sass（Dart Sass）：卸载node-sass并安装sass，同时将gulp-sass初始化改为require('gulp-sass')(require('sass'))，因node-sass无法正确解析calc()中的/，而Dart Sass交由标准CSS parser处理。
gulp-sass 编译失败：Invalid CSS after "100%" 错误
这不是 gulp 配置问题，而是 node-sass 旧解析器在词法层就崩溃了——它把 calc(100% / 3) 里的 / 当成 Sass 除法运算符，根本没识别这是 CSS 原生函数。Dart Sass 才会把 calc() 交给标准 CSS parser 处理，所以必须换底层实现。
实操上只需两步：
- 卸载
node-sass：yarn remove node-sass或npm uninstall node-sass - 安装
sass（不是dart-sass）：yarn add sass -D - 确认
gulp-sass初始化方式已更新：const sass = require('gulp-sass')(require('sass'));而不是require('node-sass')
gulp-autoprefixer 失效或样式错乱
Dart Sass 输出的是标准 CSS，不再自动加前缀；gulp-autoprefixer 必须放在 sass 编译之后、且需明确指定目标浏览器范围。常见错误是把它插在 sass 之前，或漏写 browsers 配置。
正确顺序和参数示例：
立即学习“前端免费学习笔记（深入）”；
gulp.task('sass', function() {
return gulp.src('src/scss/**/*.scss')
.pipe(sass({ outputStyle: 'compressed' }).on('error', sass.logError))
.pipe(autoprefixer({
browsers: ['last 2 versions', 'iOS >= 12', 'Android >= 6'],
cascade: false
}))
.pipe(gulp.dest('dist/css'));
});
-
browsers必须显式声明，不能依赖默认值（新版 autoprefixer 已移除内置默认） - 避免使用
last 2 Chrome versions这类模糊写法，优先用Chrome >= 90 - 若项目仍需支持 IE，
flex-gap等特性必须手动 fallback，autoprefixer 不处理
@use 语法报错：Undefined mixin 或 function
升级 Dart Sass 后，旧的全局函数（如 lighten()、map-get()）直接调用会触发 Deprecation Warning [global-builtin]，严重时构建失败。这不是警告，是未来版本的硬性限制。
修复必须改写 SCSS 文件，不能靠降级绕过：
- 所有颜色操作改用
@use "sass:color"，然后写color.lighten($c, 10%) - Map 操作改用
@use "sass:map"，然后写map.get($m, 'key') - 数学运算改用
@use "sass:math"，然后写math.div(100%, 3) -
@import全部替换为@use，且模块必须在文件顶部统一声明
Vue 2 + sass-loader 构建卡在 ::v-deep
::v-deep 在 Dart Sass 下被当作非法伪类解析，不是 loader 配置问题，是 CSS 规范层面的校验升级。Vue 2 项目里残留的 /deep/ 或 ::v-deep 写法会直接中断编译。
迁移要点很具体：
- 删除所有
/deep/和::v-deep，改用空格后代选择器：.parent >>> .child→.parent .child - 确保
sass-loader版本 ≥ 10.2.0，且配置中未硬编码implementation: require('node-sass') - 检查
vue.config.js或webpack.config.js，删掉任何指向node-sass的implementation字段 - 如果用了
vue-cli-service，运行vue inspect --rule css确认实际生效的 loader 链
真正容易被忽略的是：那些看似“只是警告”的弃用提示，比如 [global-builtin]，在 Dart Sass 3.0.0 后会变成硬错误。现在不改，下次升级就是构建崩盘。
