Element Plus 这个组件库我从它还是 Element UI 的 Alpha 版本时期就开始跟了一路用到 2026 年的今天可以说见证了 Vue 生态里这套组件库从小众走向事实标准的过程。如果你是刚接触 Vue 3 生态或者正打算把手头的老项目迁移到 Element Plus又或者只是想找一份能直接抄作业的实战手册这篇内容应该能帮你少走不少弯路。先说清楚 Element Plus 能解决什么问题它是 Vue 3 技术栈下最成熟的开源桌面端组件库之一覆盖了表单、表格、弹窗、导航、数据展示等几十个高频业务场景。说白了你做一个后台管理系统90% 的界面都能用它拼出来不用自己从零去写那些重复的弹窗、下拉、日期选择器。我会结合真实业务里踩过的坑和优化过的方案来写不会只给你贴文档。1. 为什么2026年还要选Element Plus先聊聊UI框架选型1.1 Element Plus这些年经历了什么很多人不知道 Element Plus 的底细。它脱胎于饿了么团队开源的 Element UI那套库是 Vue 2 时代后台项目的标配。Vue 3 发布之后Element UI 不再适配Element Plus 作为官方指定的 Vue 3 版本接棒从 2021 年首个稳定版到现在组件数量已经从最早的 40 多个扩展到 70 多个API 设计也在持续进化。到了 2026 年Element Plus 已经不再是Element UI 的简单升级版而是一套独立的、深度拥抱 Vue 3 Composition API 的组件体系。它的源码用 TypeScript 全量重写类型推导能力比早期版本强了不少IDE 里提示补全基本全覆盖。只要你在项目里装好写el-table的时候按下点号所有 props、slots、events 都能直接看到说明开发效率提升不是一星半点。还有一点值得注意Element Plus 已经全面统一了样式体系底层依赖的element-plus/icons-vue图标库还保持着高频更新新增组件也在往业务更细分的场景走比如虚拟化表格、水印、描述列表这类组件放到四五年前这些功能都是得自己封装的。1.2 和主流Vue UI框架的对比选型每次我写选型建议都有人让我对比 Element Plus 和其他框架。我直接拿我实际用过的感受说对比维度Element PlusAnt Design VueNaive UIVuetifyVue 3 支持官方原生适配原生适配原生适配原生适配组件丰富度非常丰富后台场景全覆盖丰富偏中后台和复杂表单中等胜在轻量丰富偏 Material 风格样式定制方式CSS 变量 SCSS 变量Less 变量 主题 tokenCSS 变量内置暗黑模式SCSS 变量国内社区热度很高中文文档完整较高蚂蚁生态加持中等口碑好一般国内用的人偏少TypeScript 支持优秀良好优秀良好适合场景后台管理系统、中后台工具大型企业中后台轻量后台、追求体验的团队跨平台桌面风格应用我的个人建议就一句话如果你的项目是国内业务、后台管理、快速交付Element Plus 基本不会出错。但如果你非常在意包体积、想要更现代的交互风格并且团队有精力去调细节Naive UI 也值得试。今天这篇就是围绕 Element Plus 展开的所以后面全部基于它来聊。2. 从零搭建Element Plus工程环境准备与项目集成2.1 Vite Vue 3 项目初始化2026 年使用 Vite 已经是常规操作比 Webpack 时代的构建体验好太多。新建项目直接跑npm create vitelatest my-admin -- --template vue-ts cd my-admin npm install npm install element-plus element-plus/icons-vue这里我强烈建议选择vue-ts模板而不是vue模板。Element Plus 的组件 props 全量带有类型定义配 TypeScript 之后写el-table-column的formatter、el-form的rules都有自动补全能挡住大量低级错误。如果你之前一直写 JavaScript趁这次上新项目可以直接切到 TS成本比想象中低。装完依赖之后一个最容易忽略的点确保你的tsconfig.json里compilerOptions包含moduleResolution: bundler否则部分组件类型解析会异常。Vite 官方模板默认带这个配置但如果你是从老项目改过来的要手动补上。2.2 全局引入与按需引入怎么选刚接触 Element Plus 的人通常会问组件是不是要一个个引入其实取决于项目规模。全局引入最省事在main.ts里写import { createApp } from vue import ElementPlus from element-plus import element-plus/dist/index.css import App from ./App.vue const app createApp(App) app.use(ElementPlus) app.mount(#app)这样所有组件和样式都会打包代码最简单适合内部后台、对首屏性能不敏感的项目。但包体积确实会大22 个组件可能变成一个 800KB 左右的 JS chunk初次加载会慢一些。按需引入配合unplugin-auto-import和unplugin-vue-components是现在主流的推荐方案配置文件如下// vite.config.ts import { defineConfig } from vite import vue from vitejs/plugin-vue import AutoImport from unplugin-auto-import/vite import Components from unplugin-vue-components/vite import { ElementPlusResolver } from unplugin-vue-components/resolvers export default defineConfig({ plugins: [ vue(), AutoImport({ resolvers: [ElementPlusResolver()] }), Components({ resolvers: [ElementPlusResolver()] }) ] })配置完成后模板里直接用el-button编译器会自动帮你引入对应的组件和样式不再需要手动import { ElButton } from element-plus。我个人实测一个中等规模后台项目按需引入能减少 30% 到 40% 的样式体积JS 体积也能降下来。建议新项目直接按需引入一次配置长期受益。2.3 从CDN快速体验如果你只是想在 HTML 页面里快速验证 Element Plus 交互效果不想搭工程那就直接用 CDN!DOCTYPE html html langzh-CN head meta charsetUTF-8 / script srchttps://unpkg.com/vue3/dist/vue.global.prod.js/script script srchttps://unpkg.com/element-plus/dist/index.full.min.js/script link relstylesheet hrefhttps://unpkg.com/element-plus/dist/index.css /head body div idapp el-button typeprimary clickvisible true点我/el-button el-dialog v-modelvisible titleCDN 测试 pHello Element Plus/p /el-dialog /div script const { createApp, ref } Vue createApp({ setup() { const visible ref(false) return { visible } } }).use(ElementPlus).mount(#app) /script /body /html这种方式的优势就是零构建、打开即用。不过我不建议生产环境用 CDN 加载因为缺少按需加载和版本锁定更新管理容易脱节更适合写 demo 或者做快速原型验证。3. 核心组件实战表单、表格、弹窗的三件套组合玩法3.1 el-form的表单校验细节后台管理系统绕不开表单。Element Plus 的el-form我用了很久最核心的是理解model、rules、prop、ref四个东西怎么配合。写一个登录表单最标准的做法如下template el-form refloginFormRef :modelloginForm :rulesloginRules label-width80px el-form-item label账号 propusername el-input v-modelloginForm.username placeholder请输入账号 / /el-form-item el-form-item label密码 proppassword el-input v-modelloginForm.password typepassword show-password / /el-form-item el-button typeprimary clickhandleLogin登录/el-button /el-form /template script setup langts import { reactive, ref } from vue import type { FormInstance, FormRules } from element-plus const loginFormRef refFormInstance() const loginForm reactive({ username: , password: }) const loginRules: FormRules { username: [ { required: true, message: 请输入账号, trigger: blur }, { min: 3, max: 20, message: 长度在 3 到 20 个字符, trigger: blur } ], password: [ { required: true, message: 请输入密码, trigger: blur }, { min: 6, message: 密码至少 6 位, trigger: blur } ] } const handleLogin async () { if (!loginFormRef.value) return await loginFormRef.value.validate() // 校验不通过会自动 reject // 校验通过后继续登录逻辑 } /script几个容易被坑的点prop必须和model里的字段名一致否则校验规则不生效。trigger决定什么时候触发校验blur是失焦change是值变化。输入框建议用blur下拉和日期选择建议用change不然体验很怪。校验方法validate返回的是 Promise使用await时校验失败会走 reject记得用 try/catch 包住别让它报未处理的 promise 异常。有一种需求是校验前先清空之前的校验状态这时候调用clearValidateloginFormRef.value.clearValidate([username, password])3.2 el-table在真实业务中的性能调优表格是后台的绝对主角。Element Plus 的el-table在使用上主要分三个层次基本渲染、服务端分页、大数据量性能优化。基本渲染大家都会el-table :datatableData border stripe el-table-column propname label姓名 width120 / el-table-column propage label年龄 width100 / el-table-column label操作 fixedright width160 template #default{ row } el-button typeprimary link clickhandleEdit(row)编辑/el-button el-button typedanger link clickhandleDelete(row)删除/el-button /template /el-table-column /el-table这里我想重点说下fixedright如果表格列很多把操作列固定住其实是后台操作效率的关键。但要留意fixed列过多时浏览器对position: sticky的绘制开销会变大一般固定一两列就够。大数据量性能优化才是重头戏。我见过有人直接把几千行数据扔给el-table结果页面卡成幻灯片。解决办法有两种用el-table-v2虚拟化表格。这是 Element Plus 提供的虚拟滚动表格只渲染可视区域的 DOM几千行也能流畅滚动。但它的 API 和el-table不同列定义使用的是类似函数式的方式上手成本稍高。如果不想换组件就用el-table的分页 懒加载策略每次只渲染当前页的 20 到 50 条数据。实际项目中服务端分页也方便查询条件和数据量统计我一般优先选这种方案。给定一个具体估算假设一行 250 像素高浏览器一屏大约显示 5 行你渲染 100 行数据也就多了 95 行 DOM。但如果你渲染 1000 行横向还有大量列树形展开、合并单元格那对内存和渲染都是一次严峻考验。所以一条经验原则是超过 500 行优先考虑服务端分页超过 2000 行必须上虚拟滚动或改成聚合数据的报表。3.3 el-dialog的层级与关闭问题弹窗在业务里非常常用但也最容易出奇怪 bug。Element Plus 的el-dialog在 Vue 3 里使用v-model绑定visible关闭时需要把状态改回去el-dialog v-modeldialogVisible title编辑用户 width600px destroy-on-close !-- 表单内容 -- /el-dialog我遇到最多的一个问题是弹窗里的表单绑定的数据没有重置。解决方式是加destroy-on-close这个属性会在关闭弹窗时销毁内部组件下次打开重新创建。不过销毁重开会带来一个折中——弹窗里的临时输入状态都会丢。所以我建议如果弹窗是新增/编辑共用就保留destroy-on-close如果弹窗里是步骤条这类需要保留进度的就不要销毁在closed事件里手动清理数据。弹窗层级问题也很典型。如果多个弹窗叠加或者弹窗里再弹确认框确认框有时会被主弹窗挡住。Element Plus 内部用z-index管理弹出层遇到层级问题时可以给弹窗显式指定append-to-body或设置modal-class并按需调高自定义 class 的 z-index。4. 主题定制与暗黑模式让Element Plus变成你的组件库4.1 CSS变量覆盖最简单的换肤方案Element Plus 2.x 及以上版本全面使用 CSS 变量管理样式。主题色的默认变量是--el-color-primary你可以在全局样式里覆盖:root { --el-color-primary: #4f46e5; --el-color-primary-light-3: #7b73e9; --el-color-primary-dark-2: #3a34b3; }这里的light-3和dark-2分别代表主色在不同交互状态下的浅色和深色变体。为什么只覆盖前三个还不够因为 Element Plus 很多组件的 hover、active、disabled 状态都依赖light-3、light-5、light-7、light-8、light-9这一系颜色。真正完整换肤的话建议用提供的 SCSS 变量方式去生成或者把所有 light 层级变量都补一遍。我用一个几百行的后台项目实测过只改--el-color-primary按钮、链接、加载条这些核心组件都会同步变色但部分带背景的组件比如el-menu的 active 背景、el-tag的浅色标签视觉上还是偏蓝。这些地方就要单独覆盖--el-color-primary-light-9这类变量相当于做一个微调。4.2 SCSS变量定制与暗黑模式切换如果你的项目本身使用 SCSS可以在构建前修改 Element Plus 的 SCSS 变量从根本上生成你要的主题。先安装sassnpm install -D sass然后在项目样式入口里添加forward element-plus/theme-chalk/src/common/var.scss with ( $colors: ( primary: ( base: #4f46e5, ), ), ); use element-plus/theme-chalk/src/index.scss as *;需要注意这种方式意味着你直接编译 Element Plus 的源码样式构建时间会稍微变长而且不能再用element-plus/dist/index.css否则两套样式会打架。优点是你能精确控制每个组件的变量比如按钮圆角、弹窗阴影、字号都能在 SCSS 层面改掉。暗黑模式这块Element Plus 官方已经内置支持。实现也不复杂在页面的根节点上添加darkclass然后在样式里引入暗黑模式变量// main.ts 里引入 import element-plus/theme-chalk/dark/css-vars.csshtml.dark { --el-color-primary: #409eff; /* 其他暗色变量 */ }如果你的系统需要做日间/暗黑切换最简单的做法是给html或body切换darkclass再配合localStorage存储用户偏好。我在实际项目里做过的方案是const toggleDark () { const htmlEl document.documentElement htmlEl.classList.toggle(dark) localStorage.setItem(theme, htmlEl.classList.contains(dark) ? dark : light) }另外注意Element Plus 暗黑模式下不是所有组件都完美适配。比如el-table的表头背景、el-card的边框在暗黑模式下看起来可能略发灰需要自己在 dark class 作用域里做少量样式覆盖。不要期待开箱即用完美至少我实测过el-table在暗色模式下行分割线偏浅会需要微调 border 颜色。5. 工程化落地国际化、权限按钮与性能优化5.1 locale国际化配置Element Plus 内置组件默认文案是英文的比如分页器的 Total、日期选择器的 month。接入国际化配置可以用官方提供的 locale。如果项目是中文的最简单import zhCn from element-plus/es/locale/lang/zh-cn app.use(ElementPlus, { locale: zhCn })对于ElConfigProvider可以更灵活地实现运行时切换语言template el-config-provider :localelocale router-view / /el-config-provider /template script setup langts import { ref } from vue import zhCn from element-plus/es/locale/lang/zh-cn import en from element-plus/es/locale/lang/en const locale ref(zhCn) // 这里根据当前语言动态切换 locale 值 /scriptElement Plus 支持的语言包很多包括中、英、日、韩、法、德、西等。需要注意locale 属性只影响组件内置文案你自己的业务文案还是得自己处理。如果项目中同时使用 Vue I18n建议把 Element Plus 的 locale 状态和 Vue I18n 语言绑定在一起保持一致。5.2 按需加载与tree-shaking实测前面提过按需引入方案这里再深入说明一下 tree-shaking 的效果。Element Plus 在发布的 npm 包里已经做了 ESM 模块化配合 Vite 和 unplugin打包器可以精准识别只引用了哪些组件其他组件代码会被摇掉。我拿一个最小 demo 做过实测只引入ElButton和ElInput产物体积从全量引入的约 750KB 降到约 200KBgzip 前整体缩小接近 70%。如果项目里还用到图标库element-plus/icons-vue同样有 tree-shaking 效果按需从包中 import不会全部打包进去。这里有一条重要的工程经验尽量使用import { ElButton } from element-plus这种具名导入方式搭配 unplugin 自动处理样式。如果手动import ElementPlus from element-plus并app.use(ElementPlus)很容易无意中把全量组件和样式都打进去导致 tree-shaking 失效。另外如果你使用的打包工具不是 Vite而是 Webpack 5记得开启sideEffects: false或使用对应插件清理未引用的样式代码。Element Plus 的部分样式文件是副作用代码不处理的话即使组件没引用样式也可能被保留。5.3 自定义指令实现权限控制后台管理系统的按钮级权限通常是按角色或权限码控制。Element Plus 并不内置权限组件但它提供了指令机制我们可以自己封装一个v-permission指令// directive/permission.ts import type { Directive, DirectiveBinding } from vue const permission: Directive { mounted(el: HTMLElement, binding: DirectiveBinding) { const requiredPermissions binding.value as string | string[] const userPermissions getCurrentUserPermissions() // 自己实现 const hasPermission Array.isArray(requiredPermissions) ? requiredPermissions.some(item userPermissions.includes(item)) : userPermissions.includes(requiredPermissions) if (!hasPermission) { el.parentNode?.removeChild(el) } } } export default permission使用方式el-button v-permissionuser:add typeprimary新增用户/el-button el-button v-permission[user:edit, user:admin] typesuccess编辑用户/el-button这种方法比在模板里写v-if干净很多而且指令只会在元素挂载时执行一次虽然权限变更时不会动态响应但对后台系统足够了。如果权限状态是异步的比如用户登录后接口还没返回建议在拿到权限之后再挂载对应区域或者用updated钩子做二次判断。6. 避坑指南2026年实操中遇到的10个常见问题我把自己带团队时遇到的 Element Plus 高频问题整理成了一个速查表每一条都踩过或看人踩过问题现象根本原因解决方案表单校验不触发prop没写或与 model 字段不一致核对prop与model字段名表单校验通过但仍无法提交validate是异步的未 await使用await formRef.validate()包裹el-dialog内部表单值残留没有销毁或重置表单开启destroy-on-close或在关闭事件手动 resetFields弹窗被遮挡多个弹层高度问题使用append-to-body或调整 z-index表格大量数据卡顿DOM 过多无虚拟滚动使用el-table-v2或服务端分页暗黑模式部分组件不生效未引入dark/css-vars.css引入样式文件并按需覆盖变量按需引入后样式缺失缺少 unplugin 配置配置vite.config.ts并重启 dev server图标不显示未安装或未注册 icons-vuenpm i element-plus/icons-vue并注册全局引入与按需引入样式冲突重复引入了两套样式二选一推荐按需引入打包后体积异常增大使用了全局注册或手动全量 import改为按需引入检查 sideEffects再补充一个比较隐蔽的问题el-input结合v-model.number的使用在用户输入非数字字符时Vue 会得到而 Element Plus 内部类型处理偶尔会有兼容差异建议在提交时做二次类型校验不要完全依赖修饰符。还有一个非常典型的坑使用el-select的远程搜索时如果每次搜索都发请求很容易出现竞态问题也就是上一次搜索的响应比后一次慢导致选项被旧数据覆盖。稳妥办法是保存一个请求序号只有最新请求能更新选项列表let requestSeq 0 const remoteSearch async (query: string) { const seq requestSeq const res await fetchOptions(query) if (seq requestSeq) { options.value res } }7. 我最后补充的几点实战建议选 Element Plus 的这两年我最大的体会就是组件库只是建筑的预制板真正决定项目好坏的是你把它组合成什么样。该用el-form的时候别自己写正则校验该用el-table的时候别手动拼接表格字符串组件库的价值就是让你把精力从轮子制造里解放出来放到业务逻辑和用户体验上。另外我强烈建议新项目里把主题变量和暗黑模式从第一天就设计进去。不要等界面全部写完了再想着换肤。CSS 变量这个东西最大的好处就是后改成本也低但如果你自己写死了一堆十六进制色值后面升级主题的时候就会非常痛苦满屏找色号实在酸爽。最后再分享一个小习惯升级 Element Plus 版本的时候别直接npm update一把梭要先去官方 Changelog 看一眼 breaking changes。我记得从 2.5 升级到 2.6 那会儿有几个组件的事件参数做了调整我的老代码直接跑出undefined排查花了不少时间。组件库升级稳字当头。