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()等  //使用例子：color.mix($primary-color, $black, 90%);
@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 *; // 自定义函数
`
}

注意： 具体的相关函数使用请参考https://sass-lang.com/documentation/modules

三、高级配置（可选项）

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排查导入问题