彻底解决 Dart Sass 升级导致的 @import 弃用警告及 Vite 缓存踩坑实录

现象定性

在近期维护基于 Vite + Vue3 + pnpm Monorepo 架构的项目时，控制台在构建阶段频繁抛出以下红色警告：

Plaintext

arduino 复制代码

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

核心根因： Sass 官方正在推进现代模块化系统升级。传统的 @import 语法由于存在"全局命名空间污染"、"变量来源难以追溯"以及"多次引入导致重复编译的性能损耗"等物理缺陷，已被标记为废弃，并将于 Dart Sass 3.0.0 版本中被彻底移除。

面对此警告，工程化处理存在"治标"与"治本"两条路径。

方案一：构建层静默（技术债延期）

如果当前处于业务高频迭代期，且项目高度依赖老旧的第三方 UI 组件库源码，没有重构预算，可以通过 Vite 底层配置强行拦截该警告。

本质上这是切断了编译器的报警感知，属于技术债的延期支付，在 Dart Sass 升级到 3.0.0 之前绝对安全。

实施路径： 在 vite.config.ts 中透传 silenceDeprecations 属性。

php 复制代码

import { defineConfig } from 'vite';

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        api: 'modern-compiler', // 必须指定现代编译器 API
        silenceDeprecations: ['import', 'global-builtin'], // 拦截特定警告
      },
    },
  },
});

方案二：语法层重构（彻底根治）

遵循第一性原理，彻底解决问题的方案是拥抱现代 SCSS 模块系统，将项目入口文件（如 main.scss）中的 @import 全部替换为 @use。

核心机制：作用域隔离（Encapsulation） @use 与 @import 的根本区别在于：@use 会将引入的模块完全封装在一个独立的命名空间（黑盒）中，拒绝隐式继承。

这意味着在重构时，必须遵守谁使用，谁声明的强依赖拓扑原则。

错误示范（旧逻辑）： main.scss 引入了 vars.scss，随后的 base.scss 就能隐式白嫖 vars.scss 里的 $primary-color 变量。
正确实践（新逻辑）： 如果 base.scss 内部用到了 $ 变量，它必须在自身文件的第一行显式声明 @use './vars/index.scss' as *;。

重构步骤：

解剖所有子模块（如 base.scss, reset.scss）。
若子模块内部存在变量调用，在其顶部补全 @use 变量域的声明。
在入口文件 main.scss 中，将所有的 @import 替换为 @use。

总结

现代前端工程正在向着**"显式依赖、拒绝隐式继承"**的方向演进。从 @import 到 @use 的迁移不仅是消除一个控制台噪音，更是从底层规范了样式的依赖拓扑，避免了未来组件库解耦时的级联崩溃。遇到依赖预构建报错时，将排查视角从代码逻辑层切换到文件物理层，即可快速破局。