feat: 重建 Bell GoAdmin 产品骨架 (#62)

2026-08-27 18:20:40 +08:00
parent b37c350096
commit f5a3dd796b
715 changed files with 75278 additions and 0 deletions
@@ -0,0 +1,90 @@
+# 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)
+