vite-plugin-element-plus-theme-builder

用于 Vite + Element Plus 项目的主题构建插件。

安装

pnpm add -D vite-plugin-element-plus-theme-builder sass

说明：使用方项目需已安装 element-plus。

快速开始

1. 在 Vite 配置中注册插件

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import { elementPlusThemeBuilder } from "vite-plugin-element-plus-theme-builder";

export default defineConfig({
  plugins: [
    vue(),
    elementPlusThemeBuilder({
      colors: {
        primary: "#215476",
      },
    }),
  ],
});

2. 在应用入口引入生成后的主题 CSS

import "./assets/generated/element-plus-theme.css";

3. 不要同时引入 Element Plus 默认整包样式

如果你同时引入了：

import "element-plus/dist/index.css";

默认样式会覆盖自定义主题，导致你的颜色看起来“没生效”。

进阶配置（可选）

如果你需要调整输出路径、扫描范围或白名单组件，可使用以下完整配置：

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import { elementPlusThemeBuilder } from "vite-plugin-element-plus-theme-builder";

export default defineConfig({
  plugins: [
    vue(),
    elementPlusThemeBuilder({
      // 最终 CSS 输出路径（相对项目根目录）
      outputCssPath: "src/assets/generated/element-plus-theme.css",

      // 扫描源码目录（相对项目根目录）
      scanSourceDir: "src",

      // 扫描文件匹配规则
      scanFilePattern: /\.(vue|jsx|tsx)$/,

      // Element Plus theme-chalk 源码路径（相对项目根目录）
      elementPlusThemeChalkDir: "node_modules/element-plus/theme-chalk/src",

      // 主题色
      colors: {
        primary: "#215476",
        success: "#67c23a",
        warning: "#e6a23c",
        danger: "#f56c6c",
        error: "#f56c6c",
        info: "#909399",
      },

      // 构建白名单：无论源码是否扫描到，都会保留这些组件样式（可选）
      alwaysIncludeComponents: [
        "base",
        "message",
        "message-box",
        "notification",
        "loading",
      ],
    }),
  ],
});

API

elementPlusThemeBuilder(options?)

统一入口方法。

• 开发模式：全量主题（基于 index.scss）
• 构建模式：按扫描结果按需输出
• 输出结果：仅最终 CSS 文件

参数说明

| 参数名 | 类型 | 默认值 | 说明 | | -------------------------- | ---------------------------- | --------------------------------------------------------------- | --------------------------------- | | outputCssPath | string | src/assets/generated/element-plus-theme.css | 最终 CSS 输出路径，基于项目根目录 | | scanSourceDir | string | src | 组件扫描目录，基于项目根目录 | | scanFilePattern | RegExp | /\.(vue\|jsx\|tsx)$/ | 扫描文件匹配规则 | | elementPlusThemeChalkDir | string | node_modules/element-plus/theme-chalk/src | Element Plus 主题源码目录 | | colors | Partial<ThemeColorPalette> | 内置默认色板 | 覆盖主题色 | | alwaysIncludeComponents | string[] | ['base', 'message', 'message-box', 'notification', 'loading'] | 构建白名单组件，始终保留样式 |

类型定义

interface ElementPlusThemePluginOptions {
  outputCssPath?: string;
  scanSourceDir?: string;
  scanFilePattern?: RegExp;
  elementPlusThemeChalkDir?: string;
  colors?: Partial<ThemeColorPalette>;
  alwaysIncludeComponents?: string[];
}

interface ThemeColorPalette {
  primary: string;
  success: string;
  warning: string;
  danger: string;
  error: string;
  info: string;
}

常见问题

1. 主题色没有变化

请检查：

1. 是否引入了生成后的 CSS 文件
2. 是否仍然引入了 element-plus/dist/index.css
3. 是否重启了开发服务器
4. 浏览器是否使用了旧缓存

2. 构建时报找不到 Element Plus 主题源码

请检查：

1. 是否安装了 element-plus
2. elementPlusThemeChalkDir 是否配置正确

3. 想扩展扫描类型（例如 .ts）

可自定义 scanFilePattern，例如：

scanFilePattern: /\.(vue|jsx|tsx|ts)$/;

注意事项

• 使用方项目需要安装 element-plus 与 sass
• 修改主题色后如未生效，请重启开发服务器
• 路径类配置建议使用相对项目根目录的写法