当前位置：首页 > news >正文

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

news 2025/9/8 16:44:13

一、项目环境（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-*;`}}}}
})