vue3 + vite + Element Plus项目中 SCSS 预处理器完整配置指南

一、项目环境 （node18.18.0）

二、基础配置（必需项）

scss: {
  // 编译器API模式：解决Element Plus兼容性警告
  // 可选值: 'modern-compiler' | 'compiler' | 'legacy' | 'auto'
  api: 'modern-compiler',
  
  // 字符集声明：禁用不必要的@charset，减少文件体积
  charset: false,
  
  // 全局注入：所有SCSS文件自动导入的代码
  additionalData: `
    @use "sass:color";    // 颜色操作函数：adjust(), mix(), scale()等
    @use "sass:math";     // 数学计算函数：div(), percentage(), sqrt()等  
    @use "sass:meta";     // 元编程函数：variable-exists(), function-exists()等
    @use "sass:string";   // 字符串处理函数：index(), insert(), slice()等
    @use "sass:list";     // 列表操作函数：append(), index(), join()等
    @use "sass:map";      // 映射操作函数：get(), merge(), remove()等
    @use "@/styles/variables.scss" as *; // 全局变量（颜色、间距、字体等）
    @use "@/styles/mixins.scss" as *;    // 全局Mixin函数
    @use "@/styles/functions.scss" as *; // 自定义函数
  `
}

三、高级配置（可选项）

scss: {
  // ================= 基础配置 =================
  api: 'modern-compiler',
  charset: false,
  
  // ================= 路径解析配置 =================
  // 导入路径搜索目录：避免冗长的相对路径
  includePaths: [
    path.resolve(__dirname, 'src/styles'),      // 项目样式目录
    path.resolve(__dirname, 'node_modules'),    // node_modules目录
    path.resolve(__dirname, 'src/components'),  // 组件目录
  ],
  
  // ================= 源码映射配置 =================
  // 源映射生成：开发环境启用，生产环境禁用
  sourceMap: process.env.NODE_ENV !== 'production',
  
  // 源映射包含内容：确保浏览器调试时显示原始SCSS文件
  sourceMapIncludeSources: true,
  
  // ================= 输出样式配置 =================
  // 输出格式：压缩模式用于生产环境
  outputStyle: process.env.NODE_ENV === 'production' ? 'compressed' : 'expanded',
  
  // 静默特定弃用警告
  silenceDeprecations: [
    'legacy-js-api',     // 忽略Legacy JS API警告
    'global-builtin',    // 忽略全局内置函数警告
  ],
  
  // ================= 调试配置 =================
  // 调试信息：开发时启用调试跟踪
  debug: process.env.NODE_ENV !== 'production',
  
  // 详细日志：输出详细的编译过程信息
  verbose: false,
  
  // ================= 自定义函数配置（高级） =================
  // 自定义Sass函数：JavaScript实现的Sass函数
  functions: {
    // 将像素转换为REM单位
    'rem($px)': function(pxValue) {
      const px = pxValue.getValue();
      return new sass.SassString(`${px / 16}rem`);
    },
    
    // 获取CSS变量值
    'css-var($name)': function(nameValue) {
      const name = nameValue.getValue();
      return new sass.SassString(`var(--${name})`);
    }
  },
  
  // ================= 导入器配置（高级） =================
  // 自定义导入解析器
  importer: [
    (url, prev) => {
      // 解析别名路径
      if (url.startsWith('@/')) {
        return {
          file: path.resolve(__dirname, 'src', url.replace('@/', ''))
        };
      }
      // 解析node_modules中的包
      if (url.startsWith('~')) {
        return {
          file: path.resolve(__dirname, 'node_modules', url.replace('~', ''))
        };
      }
      return null;
    }
  ],
  
  // ================= 全局数据配置 =================
  additionalData: `
    // ========== SASS模块导入 ==========
    @use "sass:color";
    @use "sass:math";
    @use "sass:meta";
    @use "sass:string";
    @use "sass:list";
    @use "sass:map";
    @use "sass:selector";
    
    // ========== 全局样式资源 ==========
    @use "@/styles/variables.scss" as *;
    @use "@/styles/mixins.scss" as *;
    @use "@/styles/functions.scss" as *;
    @use "@/styles/animations.scss" as *;
    
    // ========== 第三方库样式 ==========
    @use "element-plus/theme-chalk/src/common/var.scss" as *;
    
    // ========== 自定义全局变量 ==========
    $env: '${process.env.NODE_ENV}'; // 注入环境变量
    $build-time: '${new Date().toISOString()}'; // 构建时间戳
  `
}

四、环境特定配置

// 开发环境配置
const devConfig = {
  scss: {
    sourceMap: true,        // 启用源映射便于调试
    outputStyle: 'expanded', // 展开格式便于阅读
    debug: true,            // 启用调试信息
    verbose: false          // 不输出详细日志
  }
}

// 生产环境配置  
const prodConfig = {
  scss: {
    sourceMap: false,        // 禁用源映射减少体积
    outputStyle: 'compressed', // 压缩输出格式
    debug: false,            // 禁用调试信息
    charset: false           // 禁用字符集声明
  }
}

五、完整的最佳实践配置

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

export default defineConfig(({ mode }) => {
  // 加载环境变量
  const env = loadEnv(mode, process.cwd(), '')
  
  return {
    plugins: [vue()],
    resolve: {
      alias: {
        '@': resolve(__dirname, 'src'),
      },
    },
    css: {
      preprocessorOptions: {
        scss: {
          // 基础配置
          api: 'modern-compiler',
          charset: false,
          
          // 路径配置
          includePaths: [
            resolve(__dirname, 'src/styles'),
            resolve(__dirname, 'node_modules')
          ],
          
          // 输出配置
          sourceMap: mode !== 'production',
          outputStyle: mode === 'production' ? 'compressed' : 'expanded',
          
          // 静默警告
          silenceDeprecations: ['legacy-js-api', 'global-builtin'],
          
          // 全局数据注入
          additionalData: `
            // 环境变量注入
            $env: '${mode}';
            $api-base: '${env.VITE_API_BASE || ''}';
            
            // SASS模块
            @use "sass:color";
            @use "sass:math";
            @use "sass:meta";
            
            // 项目资源
            @use "@/styles/variables.scss" as *;
            @use "@/styles/mixins.scss" as *;
            
            // 第三方库变量（可选）
            @forward "element-plus/theme-chalk/src/common/var.scss" as el-*;
          `
        }
      }
    }
  }
})

六、配置说明与注意事项

1. api 选项说明

• modern-compiler: 使用最新编译器API，无警告推荐
• compiler: 传统编译器API，可能有少量警告
• legacy: 遗留API，兼容旧项目但警告多
• auto: 自动选择（默认）

2. additionalData 最佳实践

• 按功能分组导入语句
• 先导入SASS模块，再导入项目文件
• 最后导入第三方库文件
• 可注入环境变量和构建信息

3. 性能优化建议

• 生产环境禁用sourcemap减少体积
• 使用压缩输出格式
• 避免过多的全局导入影响编译速度

调试技巧

• 开发环境启用sourcemap便于浏览器调试
• 设置debug: true查看编译详情
• 使用verbose: true排查导入问题