91 lines
2.0 KiB
Markdown
91 lines
2.0 KiB
Markdown
# Sass Legacy API 废弃警告处理说明
|
||
|
||
## 问题描述
|
||
编译时出现警告：
|
||
```
|
||
Deprecation Warning [legacy-js-api]: The legacy JS API is deprecated
|
||
and will be removed in Dart Sass 2.0.0.
|
||
```
|
||
|
||
## 原因
|
||
- 项目当前使用 `sass-loader: ^13.3.3` + `sass: ^1.91.0`
|
||
- sass-loader 13.x 默认仍走 Dart Sass 的 legacy JS API（从 14.x 起才默认使用 modern API）
|
||
- Dart Sass 2.0 将移除此 API
|
||
|
||
## 解决方案
|
||
|
||
### 🎯 方案1：环境变量静默（已实施）✅
|
||
|
||
在 `.env.development` 和 `.env.production` 中添加：
|
||
|
||
```bash
|
||
SASS_SILENCE_DEPRECATIONS = 'legacy-js-api'
|
||
```
|
||
|
||
Dart Sass 会自动读取此环境变量并静默对应警告。
|
||
|
||
**优点**：
|
||
- ✅ 不需要重装依赖
|
||
- ✅ 不修改 webpack 配置
|
||
- ✅ 立即生效
|
||
- ✅ 官方推荐方式
|
||
|
||
**缺点**：
|
||
- ⚠️ 只是隐藏警告，未来 Dart Sass 2.0 可能不兼容
|
||
|
||
---
|
||
|
||
### 🚀 方案2：切换到 modern API（推荐长期方案）
|
||
|
||
升级 sass-loader 到 14+，默认使用 Dart Sass 的 modern API：
|
||
|
||
```bash
|
||
pnpm add -D sass-loader@^14.2.1
|
||
```
|
||
|
||
或在当前 13.x 下于 `vue.config.js` 中显式指定：
|
||
|
||
```js
|
||
css: {
|
||
loaderOptions: {
|
||
sass: { api: 'modern' }
|
||
}
|
||
}
|
||
```
|
||
|
||
两种方式生效后即可移除环境变量配置。
|
||
|
||
**优点**：
|
||
- ✅ 彻底解决问题
|
||
- ✅ 面向未来兼容
|
||
|
||
**缺点**：
|
||
- ⚠️ 可能需要调整配置
|
||
- ⚠️ 需要重新安装依赖
|
||
|
||
---
|
||
|
||
## 当前状态
|
||
|
||
✅ **已采用方案1**，通过环境变量静默警告。
|
||
|
||
sass-loader 虽已是 13.3.3，但仍走 legacy API，因此静默配置目前仍然必要。
|
||
建议在未来 Vue 3 稳定后，按方案2 切换到 modern API 并移除该环境变量。
|
||
|
||
---
|
||
|
||
## 验证
|
||
|
||
重启开发服务器后，编译过程中不再显示该警告：
|
||
|
||
```bash
|
||
# 需要完全重启，而不是热重载
|
||
npm run dev
|
||
```
|
||
|
||
## 参考
|
||
- [Sass Legacy JS API](https://sass-lang.com/d/legacy-js-api)
|
||
- [Sass Silencing Deprecations](https://sass-lang.com/documentation/cli/dart-sass/#silencedeprecations)
|
||
- [sass-loader v13 文档](https://github.com/webpack-contrib/sass-loader/blob/master/CHANGELOG.md)
|
||
|