一、问题背景与技术栈

在基于 Vue 3 + Vite + Element Plus 的技术栈开发时，启动开发服务器遇到了一系列 Sass 相关的警告和错误。我的环境是：

二、遇到的问题

1. Legacy JS API 弃用警告

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

2. @import 规则弃用警告

Deprecation Warning [import]: Sass @import rules are deprecated…

3. 颜色函数弃用警告

Deprecation Warning [color-functions]: lighten() is deprecated…

三、根本原因分析

1. Sass 版本升级： Dart Sass 2.0+ 引入了破坏性变更 Element Plus
2. 兼容性： UI 库内部使用了旧的 Sass API
3. 语法过时： 仍在使用已弃用的 @import 和颜色函数
4. 配置需要更新： Vite 配置需要适配新的 Sass 标准

四、解决方案

1. vite.config.js 核心配置

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { resolve } from 'path'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': resolve(__dirname, 'src'),
    },
  },
  css: {
    preprocessorOptions: {
      scss: {
        api: 'modern-compiler', // 关键：解决 Element Plus 兼容性问题
        charset: false,         // 禁用不必要的 @charset 声明
        additionalData: `
          @use "sass:color";    // 颜色函数模块
          @use "sass:math";     // 数学函数模块  
          @use "sass:meta";     // 元函数模块
          @use "@/styles/variables.scss" as *; // 全局变量
        `
      }
    }
  }
})

注意： SCSS 预处理器配置指南可供参考

2. 全局配置的优势

通过 additionalData 配置，所有 SCSS 文件自动获得以下能力：

• 无需手动导入： 无需在每个文件重复添加 @use 语句
• 全局变量访问： 所有变量、mixin、函数全局可用
• 模块化支持： 直接使用 color.mix()、math.div() 等函数
• 统一管理： 集中维护导入和配置

3. Sass 语法迁移指南

颜色函数迁移

// scss
/* 弃用 → 推荐 */
lighten($color, 10%)    → color.adjust($color, $lightness: 10%)
darken($color, 10%)     → color.adjust($color, $lightness: -10%) 
mix($color1, $color2, 50%) → color.mix($color1, $color2, 50%)
transparentize($color, 0.1) → color.adjust($color, $alpha: -0.1)

导入方式迁移

/* 弃用 */
@import "variables";
@import "mixins";

/* 推荐 */
// 在 vite.config.js 中全局配置，无需在每个文件重复导入

4.实践总结

1. 使用 api: 'modern-compiler'： 解决 Element Plus 兼容性，Legacy JS API 弃用警告
2. 全局配置 additionalData： 在 vite.config.js 中全局配置，避免重复导入
3. 迁移到新颜色函数： 使用 color. 模块函数
4. 统一代码风格： 所有组件使用相同的 Sass 语法