Element Plus SCSS变量覆盖与Vite自动导入实践

脚本专家

在基于 Vite + Vue 3 的项目中使用 Element Plus 时，定制主题色最常见的方式是通过 SCSS 变量覆盖。Element Plus 的组件样式基于 SCSS 构建，官方保留了底层变量入口，我们可以利用 Sass 的 @forward ... with 将自定义变量注入到主题包中，再配合 unplugin-auto-import / unplugin-vue-components 的 sass importStyle，在自动导入组件的同时应用自定义配色。

1. 安装 Sass 依赖

由于 Element Plus 的 SCSS 变量覆盖依赖 sass 模块系统，需要先安装 sass。如果项目使用 pnpm，命令如下：

2. pnpm i sass -D

复制代码

2. 创建变量覆盖样式文件

新建 element-plus-vars.scss，在文件最前面使用 @forward 覆盖 Element Plus 主题变量。这里以主色、状态色和页面背景色为例：

2. // 覆盖变量
3. @forward "element-plus/theme-chalk/src/common/var.scss" with (
4.   $colors: (
5.     "primary": (
6.       "base": #4080ff,
7.     ),
8.     "success": (
9.       "base": #23c343,
10.     ),
11.     "warning": (
12.       "base": #ff9a2e,
13.     ),
14.     "danger": (
15.       "base": #f76560,
16.     ),
17.     "info": (
18.       "base": #a9aeb8,
19.     ),
20.   ),
21.   $bg-color: (
22.     "page": #f5f8fd,
23.   )
24. );

复制代码

需要注意的是，@forward 必须在 @use 之前执行。变量覆盖完成后，再引入 Element Plus 的完整样式入口。按照官方模块规则，可以在同一文件中随后加入：

2. @use "element-plus/theme-chalk/src/index.scss";

复制代码

3. 建立组件样式统一入口

实际项目中，建议单独创建一个 element-plus.scss，作为 Element Plus 组件样式覆盖的集中文件，并在该文件中先引入上面写好的变量覆盖文件，再引入 Element Plus 样式，保证覆盖顺序正确：

2. /**
3. * element-plus 组件样式覆盖
4. */
5. // 变量覆盖(必须在最前面)
6. @use "./element-plus-vars";
8. // 引入 Element Plus 样式（必须在覆盖变量后）
9. @use "element-plus/theme-chalk/src/index.scss";

复制代码

如果你还有其他全局样式，比如 reset.scss，可以再建一个入口文件 index.scss，按顺序组织：

2. // 重置样式
3. @use "./reset";
5. // element-plus
6. @use "./element-plus";

复制代码

4. 在入口文件中导入样式

在 Vite 项目的 main.js 中引入上面的样式入口文件即可，确保它在组件注册逻辑加载前被处理：

2. // 样式导入
3. import "@/assets/styles/index.scss";

复制代码

5. 配置 Vite 自动导入组件并启用 Sass 样式

通过 unplugin-auto-import 和 unplugin-vue-components 可以避免手动 import Element Plus 组件。关键点在于给 ElementPlusResolver 传入 importStyle: "sass"，让组件按需加载时使用 sass 版本样式，从而读取前面覆盖过的 SCSS 变量。

文件 vite.config.js 中相关的配置如下：

2. // 自动导入
3. import AutoImport from 'unplugin-auto-import/vite'
4. import Components from 'unplugin-vue-components/vite'
5. import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
7. export default {
8.   plugins: [
9.     vue(),
10.     // 自动导入 Element Plus 组件和函数，无需手动 import
11.     AutoImport({
12.       resolvers: [ElementPlusResolver()],
13.     }),
14.     // 自动注册 Element Plus 组件，可在模板中直接使用，采用 sass 样式配色
15.     Components({
16.       resolvers: [ElementPlusResolver({ importStyle: "sass" })],
17.     }),
18.   ],
19. }

复制代码

完成以上配置后，Element Plus 的组件主题色就会覆盖为变量中定义的色值，同时保留按需自动导入的能力。整个方案的核心是把变量覆盖文件放在所有组件样式之前，并且让 Vite 插件按 sass 方式拉取组件样式，否则 SCSS 变量无法传入，定制不会生效。

这种写法的适用场景是：Vue 3 + Vite + Element Plus 项目需要统一品牌色、调整 primary/status 颜色，或修改页面背景色等。需要注意的是，覆盖文件中的变量结构要与 Element Plus 的 var.scss 定义保持一致，特别是 $colors 下每个状态色需要包含 base 字段。后续要调整其他深度变量，也可以继续在 with 块中追加对应项，比如圆角、尺寸或阴影变量均可以在同一个 @forward 中覆盖。