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
2
3
4
5
6
7
8
9
10
// main.ts
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import zhCn from 'element-plus/es/locale/lang/zh-cn'
import 'element-plus/dist/index.css'
import App from './App.vue'

const app = createApp(App)
app.use(ElementPlus, { locale: zhCn })
app.mount('#app')

模板里直接写 <el-button>,不必在页面里 import。

按需:安装插件

运行时依赖保持安装状态,只加开发依赖:

1
2
# 已有 element-plus 时不要 uninstall
npm i -D unplugin-vue-components unplugin-auto-import
包 作用
unplugin-vue-components 扫描模板里的组件标签,按需注册并引入对应样式
unplugin-auto-import 自动导入 ElMessage、ElMessageBox 等 API
ElementPlusResolver 上面两个插件识别 Element Plus 的解析器(随 unplugin-vue-components 提供)

按需:配置 Vite

在 vite.config.ts 的 plugins 里与 vue() 并列增加:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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({
// 自动导入 ElMessage 等 API,并带上样式
resolvers: [ElementPlusResolver()],
}),
Components({
// 模板中的 <el-button> 等按需注册,并引入对应样式
resolvers: [ElementPlusResolver()],
}),
],
})

用 Sass 变量定制主题时,可写成 ElementPlusResolver({ importStyle: 'sass' })。未定制主题时用默认即可。

按需:改入口,去掉全量注册

1
2
3
4
5
// main.ts 中删除这类全量用法
// import ElementPlus from 'element-plus'
// import zhCn from 'element-plus/es/locale/lang/zh-cn'
// import 'element-plus/dist/index.css'
// app.use(ElementPlus, { locale: zhCn })

保留 Pinia、路由、业务样式等即可。

按需时的语言包

不要再用 app.use(ElementPlus, { locale }) 设语言,那等于又全量引入。用 ElConfigProvider 包一层根视图:

1
2
3
4
5
6
7
8
9
10
<script setup lang="ts">
import { ElConfigProvider } from 'element-plus'
import zhCn from 'element-plus/es/locale/lang/zh-cn'
</script>

<template>
<el-config-provider :locale="zhCn">
<router-view />
</el-config-provider>
</template>

日期类组件依赖 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
2
3
4
5
import * as ElementPlusIconsVue from '@element-plus/icons-vue'

for (const [key, component] of Object.entries(ElementPlusIconsVue)) {
app.component(key, component)
}

模板里可用 <component :is="iconName" />,iconName 来自路由 meta 等配置。

按需:页面显式导入

适合页面里少量固定图标:

1
2
3
4
5
6
7
<script setup lang="ts">
import { Odometer, Tickets } from '@element-plus/icons-vue'
</script>

<template>
<el-icon><Odometer /></el-icon>
</template>

按需:白名单注册

仍要用字符串动态渲染时,只注册实际用到的图标,与路由 / 菜单配置保持同步:

1
2
3
4
5
6
import { Odometer, Tickets, Message } from '@element-plus/icons-vue'

const icons = { Odometer, Tickets, Message }
for (const [name, component] of Object.entries(icons)) {
app.component(name, component)
}

新增菜单图标时必须同步改这份列表,否则 <component :is="icon" /> 会空白。

也可用 unplugin-icons 做自动按需,写法常变成 i-ep-odometer 一类,与 meta.icon: 'Odometer' 这类约定不一致,改造成本更高,现有动态图标体系一般不必强行上。

ECharts

全量写法

1
2
3
4
import * as echarts from 'echarts'

const chart = echarts.init(el)
chart.setOption(option)

所有图表类型和组件都会进包,写法简单。

按需写法(Tree Shaking)

ECharts 5+ 支持按图表类型与组件注册。集中在一个封装组件里改即可,业务页只传 option:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import * as echarts from 'echarts/core'
import { LineChart, BarChart, PieChart } from 'echarts/charts'
import {
GridComponent,
TooltipComponent,
LegendComponent,
// option 若用到 dataZoom、visualMap 等,在此追加
} from 'echarts/components'
import { CanvasRenderer } from 'echarts/renderers'

echarts.use([
LineChart,
BarChart,
PieChart,
GridComponent,
TooltipComponent,
LegendComponent,
CanvasRenderer,
])

const chart = echarts.init(el)

类型可继续用宽松的 EChartsOption,或按官方方式用 ComposeOption 收窄为本项目用到的组合。仅 import type 的类型导入不进运行时包。

注意点

  • option 里用了未 use 的系列或组件时,图表空白或控制台报错,需对照页面补全

  • 改前先扫一遍项目里实际用到的图表类型和组件,再定 use 列表

改造检查清单

若从全量改到按需,按下面顺序做:

  1. 安装并配置 unplugin-vue-components、unplugin-auto-import;保留 element-plus / icons / echarts 依赖

  2. 去掉入口中 Element Plus 全量 use 与全量 CSS(不要 uninstall 包)

  3. 根组件用 el-config-provider 设语言,并引入 dayjs/locale/zh-cn

  4. 决定图标策略:显式导入、白名单注册,或暂时全量保留

  5. 图表封装改为 echarts/core + 按需 use

  6. 跑类型检查与 npm run build,本地过一遍主要页面

  7. 对比改造前后 dist/ 体积;下降不明显可回退

和脚手架文章的关系

用 用 create-vue 创建 Vue 3 项目 生成的工程默认没有 Element Plus / ECharts。需要时先安装运行时依赖:

1
npm install element-plus @element-plus/icons-vue echarts

然后在全量与按需之间按本文选择。内网学习、后台原型优先全量;要对公网压首包时再按上面步骤改。