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` 选项。

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

**文件：`vue.config.js`**

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

```js
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` 模块：

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

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

```diff
  @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` 改造完成后移除。