mes-ui-d2/docs/sass-deprecation-fixes.md

Sass 废弃警告修复记录

项目运行 pnpm serve 时，Dart Sass 输出了多类废弃 API 警告。本文档记录问题现象、根因及修复方案。

---

1. legacy-js-api — Sass Loader 旧 JS API 警告

问题现象

Deprecation Warning [legacy-js-api]: The legacy JS API is deprecated and will be removed in Dart Sass 2.0.0.

根因

sass-loader 旧版本默认通过旧版 JS API 调用 Dart Sass。Dart Sass 计划在 2.0 中移除该 API。

修复

文件：package.json

将 sass-loader 升级到 10.5.2（v10 最后一个稳定版，兼容 Webpack 4），该版本支持 silenceDeprecations 选项。

- "sass-loader": "^10.3.1",
+ "sass-loader": "~10.5.2",

文件：vue.config.js

在 css.loaderOptions.sass 中添加 silenceDeprecations 配置。

sass: {
  additionalData: '@use "@/assets/style/public.scss" as *;',
  sassOptions: {
    silenceDeprecations: ['legacy-js-api', 'import']
  }
},

---

2. import — Sass @import 废弃警告

问题现象

DEPRECATION WARNING [import]: Sass @import rules are deprecated and will be removed in Dart Sass 3.0.0.

  ╷
1 │ @import '~@/assets/style/unit/color.scss';
  │         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  ╵
    src\assets\style\public.scss 1:9          @use

根因

public.scss 通过 @import '~@/assets/style/unit/color.scss' 引入颜色变量文件。Dart Sass 正在推动从 @import 迁移到 @use / @forward 模块系统。

为何不改成 @use

该 @import 使用了 Webpack 专有的 ~ 前缀做模块路径解析（~@/assets/...），@use 对此机制支持不稳定，直接替换可能导致构建失败。

修复

在上述 silenceDeprecations 数组中追加 'import'，静默该警告。

---

3. global-builtin — 全局内置函数 nth() 废弃警告

问题现象

Deprecation Warning [global-builtin]: Global built-in functions are deprecated and will be removed in Dart Sass 3.0.0.
Use list.nth instead.

   ╷
42 │   .#{$prefix}-m-#{nth($sizes, $index)} { margin: #{nth($sizes, $index)}px !important; }
   │                   ^^^^^^^^^^^^^^^^^^^
   ╵
    src\assets\style\public-class.scss 42:19  @import
    src\App.vue 3:9                           root stylesheet

根因

Dart Sass 正在将全局内置函数迁移到命名空间模块。nth() 属于 sass:list 模块，不应再作为全局函数直接调用。

修复（从源码根治）

文件：src/assets/style/public-class.scss

步骤 1 — 文件顶部引入 sass:list 模块：

+ @use 'sass:list';
  @import 'public';

步骤 2 — 将 @for 循环中所有 nth() 替换为 list.nth()：

  @for $index from 1 to 6 {
-   .#{$prefix}-m-#{nth($sizes, $index)} { margin: #{nth($sizes, $index)}px !important; }
-   .#{$prefix}-mt-#{nth($sizes, $index)} { margin-top: #{nth($sizes, $index)}px !important; }
-   .#{$prefix}-mr-#{nth($sizes, $index)} { margin-right: #{nth($sizes, $index)}px !important; }
-   .#{$prefix}-mb-#{nth($sizes, $index)} { margin-bottom: #{nth($sizes, $index)}px !important; }
-   .#{$prefix}-ml-#{nth($sizes, $index)} { margin-left: #{nth($sizes, $index)}px !important; }
-   .#{$prefix}-p-#{nth($sizes, $index)} { padding: #{nth($sizes, $index)}px !important; }
-   .#{$prefix}-pt-#{nth($sizes, $index)} { padding-top: #{nth($sizes, $index)}px !important; }
-   .#{$prefix}-pr-#{nth($sizes, $index)} { padding-right: #{nth($sizes, $index)}px !important; }
-   .#{$prefix}-pb-#{nth($sizes, $index)} { padding-bottom: #{nth($sizes, $index)}px !important; }
-   .#{$prefix}-pl-#{nth($sizes, $index)} { padding-left: #{nth($sizes, $index)}px !important; }
+   .#{$prefix}-m-#{list.nth($sizes, $index)} { margin: #{list.nth($sizes, $index)}px !important; }
+   .#{$prefix}-mt-#{list.nth($sizes, $index)} { margin-top: #{list.nth($sizes, $index)}px !important; }
+   .#{$prefix}-mr-#{list.nth($sizes, $index)} { margin-right: #{list.nth($sizes, $index)}px !important; }
+   .#{$prefix}-mb-#{list.nth($sizes, $index)} { margin-bottom: #{list.nth($sizes, $index)}px !important; }
+   .#{$prefix}-ml-#{list.nth($sizes, $index)} { margin-left: #{list.nth($sizes, $index)}px !important; }
+   .#{$prefix}-p-#{list.nth($sizes, $index)} { padding: #{list.nth($sizes, $index)}px !important; }
+   .#{$prefix}-pt-#{list.nth($sizes, $index)} { padding-top: #{list.nth($sizes, $index)}px !important; }
+   .#{$prefix}-pr-#{list.nth($sizes, $index)} { padding-right: #{list.nth($sizes, $index)}px !important; }
+   .#{$prefix}-pb-#{list.nth($sizes, $index)} { padding-bottom: #{list.nth($sizes, $index)}px !important; }
+   .#{$prefix}-pl-#{list.nth($sizes, $index)} { padding-left: #{list.nth($sizes, $index)}px !important; }
  }

---

涉及文件汇总

文件	修改内容
package.json	sass-loader 版本 ^10.3.1 → ~10.5.2
vue.config.js	添加 sassOptions.silenceDeprecations 配置
src/assets/style/public-class.scss	引入 sass:list 模块，nth() → list.nth()

---

后续建议

• 当项目未来升级到 Vue CLI 5 / Webpack 5 时，可考虑将 public.scss 中的 @import 改为 @use（届时 ~ 前缀路径的兼容方案需要重新评估）。
• silenceDeprecations 中的 'import' 为临时静默方案，待 @import 改造完成后移除。