做一个 Element Plus 按需主题的 Vite 插件

@rdeam/vite-plugin-element-plus-me-builder 是一个 Vite 插件，专注于两件事：

1. 根据你自定义的主题色重新编译 Element Plus 样式。
2. 只把页面实际使用到的组件 CSS 打入产物，显著削减体积。

解决什么痛点

在实际项目中，团队经常面临以下困扰：

• 官方两条主题定制方法都不够友好：
• 直接覆盖 :root { --el-color-primary: …不过，}——只能改一层颜色，派生梯度仍然是默认值。
• 使用 SCSS 入口 + @forward …with——需要手动维护繁琐的 @use 清单，且仍需一次性引入完整的 element-plus/dist/index.css导致包体积居高不下。
• 按需加载难以实现：Element Plus 没有开箱即用的按需 CSS 打包方案，需要自行写插件或脚本。
• 维护成本高：每次改动主题色后都要重新编译、手动更新引用，容易出错且影响开发效率。

快速使用

pnpm add -D @rdeam/vite-plugin-element-plus-me-builder sass

// vite.config.ts
import { defineConfig } from 'vite';import vue from '@vitejs/plugin-vue';import { elementPlusThemeBuilder } from '@rdeam/vite-plugin-element-plus-me-builder';export default defineConfig({
plugins:,});

无需在 main.ts 手动写 import './xxx.css'插件会自动把对应的  标签注入到 index.html 中。

工作原理

整体流程

transform → 扫描每个模块。记录用到的组件名
generateBundle → 根据收集到的组件清单调用 Sass 编译主题 CSS
emitFile → 把 CSS 当作资源交给 Vite
transformIndexHtml → 把  写进 index.html

1️⃣ 收集组件：transform hook + 三个正则

插件在 Vite 的 transform 阶段挂钩（enforce: 'pre')，确保在 Vue SFC 编译前拿到模板原文。

{
至于name。'element-plus-me-builder',enforce: 'pre',transform {
scanCode;},}

三个正则覆盖所有可能出现的 Element Plus 标识：

• /<\s*/g ——匹配模板中的标签如 
• /\b\b/g ——匹配 JSX/TSX 中的组件名如 ElButton
• /\s*\\)/g ——匹配已被 Vue 编译成调用形式的动态组件

痛点：即使是已经被 Vue 编译过、模板文字消失的代码。也能被第三条正则捕获，从而不遗漏任何样式。

2️⃣ 编译：动态生成 SCSS 入口文件

在 generateBundle 阶段。根据收集到的组件列表拼接临时 SCSS 内容：

@forward "/common/var.scss" with (
$colors: (
"primary":,//…其余颜色保持默认或自行
));@use "/button.scss" as *;@use "/dialog.scss" as *;// ... 按需引入所有被使用的组件 SCSS

随后交给  得到最终 CSS。

3️⃣ 输出：emitFile，不污染源码目录

this.emitFile({
type这方面。'asset',name: 'element-plus-me.css',source: css,});

C​SS 文件名会自动附加 content hash。随 Vite 一起落盘至 dist/ ,完全不影响 src/ 。随后通过 transformIndexHtml 将 注入页面。注入位置可配置为 "head","head-prepend"。 "body","body-prepend"；默认放在 "head"。按理说，

4️⃣ 开发模式：全量主题直接内存提供

在 dev 环境下插件不进行扫描。而是一次性编译完整主题 CSS 并通过中间件提供：

async configureServer {
devThemeCss = await compileThemeCss;server.middlewares.use => {
res.setHeader;res.end，});}

Pain point 解答：If you modify a component during development you won’t suffer from missing styles because full me is always available.

白名单兜底

组件	为什么扫不到
base	全局基础样式，没有具体标识符
overlay	message-box / notification 内部使用，无 标签
message	通过 ElMessage 调用，没有标签
message-box	通过 ElMessageBox.confirm 调用，没有标签
notification	通过 ElNotification 调用。没有标签
loading	ElLoading.service 或 v-loading 指令调用，没有标签

Pain point：If you rely solely on static scanning,se API‑style components would miss ir CSS and appear unstyled.

You usually **don’t** need to add ordinary template components to whitelist—doing so would only bloat final CSS.

The only scenario that requires extending whitelist is when component names are built dynamically at runtime – static analysis simply can’t see m.

配置项

& nbsp;elementPlusThemeBuilder;不过，& n bsp，// 简单示例。仅修改主色

ts elementPlusThemeBuilder({ // 🎨 主色调，仅此字段必填；其余颜色会自动生成梯度 至于colors，{ primary: '#409eff',success: '#67c23a',warning: '#e6a23c'。danger : '#f56c6c',error : '#f56c6c',info : '#909399',},

// 📌 link 标签注入位置。'head-prepend' 可让业务样式覆盖主题样式 injectTo: 'head',

// 📦 白名单兜底。除非有运行时拼接组件名，否则保持默认即可 alwaysIncludeComponents:。

// 🔍 扫描哪些文件后缀。想让 .md、.svelte 等也参与扫描，可自行 scanFilePattern: /.$/,

// ⚡ 性能调优：如果你的项目根本不依赖 Element Plus 的某些大包。可在这里排除，以跳过无意义扫描 scanIgnore:,

// 📁 me‑chalk SCSS 源码所在目录。大多数情况下无需修改，pnpm hoist 场景下可能需要指向 workspace 根目录 elementPlusThemeChalkDir: 'node_modules/element-plus/me-chalk/src',});不过，

Pain point relief:If you’re only interested in changing a few brand colors。just fill in  colors​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​‌​​‌‌‍‌‍‍‍‍‍‍‍‌‌‌‌‌‌‌‌‎‎‏‏‏‏‏‏‎‎‎​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​‏‏‏‌​​\`colors\` field—everything else works out‑of‑‑box.

FAQ

• 改了 /colors/ 没生效？<\/ strong> SOLUTION: 重启 dev server。颜色在 /configureServer/   provided once at startup and won’t hot‑reload automatically.

报错找不到 me‑chalk？<\/ strong>& nbsp;Check that /element‑plus/& nbsp;is installed. If you’re using pnpm workspaces and node_modules lives at workspace root,set /elementPlusThemeChalkDir/& nbsp;其实，accordingly.

想让业务样式覆盖主题样式？<\/ strong>& nbsp;其实，Set /injectTo/: '"head-prepend"'/. This places me link at very beginning of so your own styles win in cascade order.

某个组件没有样式？<\/ strong>& nbsp;If its name comes from a runtime variable,add that component’s identifier to alwaysIncludeComponents. Do not add ordinary template components—orwise you’ll bloat your bundle.

.

---