Vue 3 全量引入与按需导入
摘要
- 说明 Element Plus、
@element-plus/icons-vue、ECharts 的全量引入与按需导入差在哪里、适合什么场景,以及按需时要装哪些插件、怎么改 Vite 与入口代码 - 本文按 Vue 3 + Vite。示例对应 Element Plus
2.x、ECharts5+/6.x、unplugin-vue-components@32.x、unplugin-auto-import@21.x - 官方文档:Element Plus 快速开始、Element Plus 国际化、ECharts 按需引入。脚手架创建见 用 create-vue 创建 Vue 3 项目
两种引入方式差在哪
| 全量引入 | 按需导入 | |
|---|---|---|
| 做法 | 入口一次 app.use(ElementPlus),或 import * as echarts from 'echarts' |
构建期只打进用到的组件 / 图表 / 样式 |
| 首包体积 | 大,未用到的也会进包 | 通常更小 |
| 写法成本 | 低,模板里直接用 | 要配插件,或手写 import / echarts.use |
| 维护点 | 少 | 动态组件名、漏注册图表时要补;改造后要对比 dist 体积 |
| 典型场景 | 内网后台、功能面广、优先稳定 | 公网首屏、包体积已成为明确瓶颈 |
按需导入不会换成别的 npm 包。element-plus、@element-plus/icons-vue、echarts 仍留在 dependencies 里;改的是从这些包里拆出用到的模块。需要新增的是开发依赖(如 unplugin-vue-components、unplugin-auto-import)。需要删掉的是代码里的全量用法,不是 npm uninstall 这些库。
配了按需插件之后,入口里若仍保留 app.use(ElementPlus) 和 import 'element-plus/dist/index.css',构建仍会把整库打进去,体积与全量无异。两种写法不要叠在一起。
什么时候用全量,什么时候按需
适合继续全量:
-
内网管理系统,带宽和首屏不是痛点
-
页面大量使用组件库,按需省下的体积有限
-
侧边栏等用字符串动态渲染图标(
meta.icon),全量全局注册更省事 -
团队优先少配置、少踩「漏注册」类问题
适合改成按需:
-
公网或移动端,要压首包、改善首屏
-
npm run build后产物体积已成明确瓶颈 -
实际只用到少量组件或少数图表类型
改造后务必对比 dist/ 体积并过一遍关键页面。下降不明显就回退,避免白增加维护成本。
Element Plus 组件
全量写法
1 | // main.ts |
模板里直接写 <el-button>,不必在页面里 import。
按需:安装插件
运行时依赖保持安装状态,只加开发依赖:
1 | # 已有 element-plus 时不要 uninstall |
| 包 | 作用 |
|---|---|
unplugin-vue-components |
扫描模板里的组件标签,按需注册并引入对应样式 |
unplugin-auto-import |
自动导入 ElMessage、ElMessageBox 等 API |
ElementPlusResolver |
上面两个插件识别 Element Plus 的解析器(随 unplugin-vue-components 提供) |
按需:配置 Vite
在 vite.config.ts 的 plugins 里与 vue() 并列增加:
1 | import { defineConfig } from 'vite' |
用 Sass 变量定制主题时,可写成 ElementPlusResolver({ importStyle: 'sass' })。未定制主题时用默认即可。
按需:改入口,去掉全量注册
1 | // main.ts 中删除这类全量用法 |
保留 Pinia、路由、业务样式等即可。
按需时的语言包
不要再用 app.use(ElementPlus, { locale }) 设语言,那等于又全量引入。用 ElConfigProvider 包一层根视图:
1 | <script setup lang="ts"> |
日期类组件依赖 Day.js,还需在入口引入:
1 | import 'dayjs/locale/zh-cn' |
按需注意点
-
模板里继续写
<el-button>;脚本里手动调用的ElMessage等由AutoImport+ElementPlusResolver处理 -
动态组件名,或 resolver 未覆盖到的用法,改为显式
import { ElXxx } from 'element-plus' -
改完跑
npm run build,确认体积下降且各页面组件显示正常
Element Plus 图标
全量全局注册
适合菜单、底栏按名称字符串动态渲染:
1 | import * as ElementPlusIconsVue from '@element-plus/icons-vue' |
模板里可用 <component :is="iconName" />,iconName 来自路由 meta 等配置。
按需:页面显式导入
适合页面里少量固定图标:
1 | <script setup lang="ts"> |
按需:白名单注册
仍要用字符串动态渲染时,只注册实际用到的图标,与路由 / 菜单配置保持同步:
1 | import { Odometer, Tickets, Message } from '@element-plus/icons-vue' |
新增菜单图标时必须同步改这份列表,否则 <component :is="icon" /> 会空白。
也可用 unplugin-icons 做自动按需,写法常变成 i-ep-odometer 一类,与 meta.icon: 'Odometer' 这类约定不一致,改造成本更高,现有动态图标体系一般不必强行上。
ECharts
全量写法
1 | import * as echarts from 'echarts' |
所有图表类型和组件都会进包,写法简单。
按需写法(Tree Shaking)
ECharts 5+ 支持按图表类型与组件注册。集中在一个封装组件里改即可,业务页只传 option:
1 | import * as echarts from 'echarts/core' |
类型可继续用宽松的 EChartsOption,或按官方方式用 ComposeOption 收窄为本项目用到的组合。仅 import type 的类型导入不进运行时包。
注意点
-
option里用了未use的系列或组件时,图表空白或控制台报错,需对照页面补全 -
改前先扫一遍项目里实际用到的图表类型和组件,再定
use列表
改造检查清单
若从全量改到按需,按下面顺序做:
-
安装并配置
unplugin-vue-components、unplugin-auto-import;保留element-plus/ icons /echarts依赖 -
去掉入口中 Element Plus 全量
use与全量 CSS(不要 uninstall 包) -
根组件用
el-config-provider设语言,并引入dayjs/locale/zh-cn -
决定图标策略:显式导入、白名单注册,或暂时全量保留
-
图表封装改为
echarts/core+ 按需use -
跑类型检查与
npm run build,本地过一遍主要页面 -
对比改造前后
dist/体积;下降不明显可回退
和脚手架文章的关系
用 用 create-vue 创建 Vue 3 项目 生成的工程默认没有 Element Plus / ECharts。需要时先安装运行时依赖:
1 | npm install element-plus @element-plus/icons-vue echarts |
然后在全量与按需之间按本文选择。内网学习、后台原型优先全量;要对公网压首包时再按上面步骤改。