Element Plus 按需引入的配置使用说明和完整示例

在 Vue 3 + Vite 项目中，Element Plus 的按需引入是优化打包体积、提升首屏加载速度的核心步骤。以下是完整的配置说明与实战示例：

一、 核心配置步骤

1. 安装核心依赖

除了 Element Plus 本体，还需要安装两个自动导入插件：

pnpm add element-plus
pnpm add -D unplugin-vue-components unplugin-auto-import

**2. 配置 ****vite.config.ts**

在 Vite 配置文件中注册这两个插件，并指定 Element Plus 的解析器：

// 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()],
    }),
  ],
})

3. 清理 **main.ts** 全局引入

配置完上述插件后，不再需要 在 main.ts 中全局引入 Element Plus 及其样式文件。直接挂载应用即可：

// main.ts
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)
app.mount('#app')

---

二、 完整实战示例

配置完成后，你可以在任何组件中直接使用 <el-xxx> 标签和 ElXxx API，插件会自动处理导入和样式。

<template>
  <div class="login-page">
    <!-- 直接使用组件，无需手动 import ElForm, ElInput, ElButton -->
    <el-form :model="form" label-width="80px">
      <el-form-item label="用户名">
        <el-input v-model="form.username" placeholder="请输入用户名" />
      </el-form-item>
      <el-form-item label="密码">
        <el-input v-model="form.password" type="password" placeholder="请输入密码" />
      </el-form-item>
      <el-form-item>
        <el-button type="primary" @click="handleLogin">登录</el-button>
      </el-form-item>
    </el-form>
  </div>
</template>

<script setup lang="ts">
import { reactive } from 'vue'
// 注意：ElMessage 同样会被自动导入，直接调用即可
// import { ElMessage } from 'element-plus'  <-- 这行可以省略

const form = reactive({
  username: '',
  password: ''
})

const handleLogin = () => {
  if (!form.username || !form.password) {
    ElMessage.warning('请填写完整信息')
    return
  }
  ElMessage.success('登录成功！')
}
</script>

---

三、 图标（Icons）的特殊处理

Element Plus 从某版本起将图标独立为 @element-plus/icons-vue 包。自动导入插件不会自动处理图标，你需要手动处理：

方案 A：按需手动引入（推荐，最省体积）

pnpm add @element-plus/icons-vue

<script setup lang="ts">
import { Edit, Delete } from '@element-plus/icons-vue'
</script>

<template>
  <el-button :icon="Edit">编辑</el-button>
  <el-button :icon="Delete" type="danger">删除</el-button>
</template>

方案 B：全局注册（适合图标使用极频繁的项目）

在 main.ts 中一次性注册所有图标：

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import * as ElementPlusIconsVue from '@element-plus/icons-vue'

const app = createApp(App)
for (const [key, component] of Object.entries(ElementPlusIconsVue)) {
  app.component(key, component)
}
app.mount('#app')

---

四、 避坑指南

1. 动态组件样式丢失 ：如果你发现 ElMessage、ElNotification 等通过 JS 调用的组件没有样式，可以在 vite.config.ts 中补充 unplugin-element-plus 插件，并开启 useSource: true：
2. 表单验证失效 ：使用 el-form-item 时，务必加上 prop="字段名" 属性，否则校验规则不会生效。
3. TypeScript 类型提示 ：如果 TS 无法识别 <el-xxx> 标签，在 tsconfig.json 的 compilerOptions.types 中添加 "element-plus/global"。
4. 主题定制 ：Element Plus 基于 CSS 变量，直接在 App.vue 或全局样式中覆盖即可：

按照这套配置，你的项目打包体积会显著下降，同时享受极致的开发体验。