企业官网建设流程全解析

Element Plus 快速上手指南：全量引入、按需引入与全局配置详解

【免费下载链接】element-plus🎉 A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus

本篇指南围绕 Element Plus（Vue 3 组件库）的接入方式进行系统讲解，覆盖全量引入、Volar 类型支持、基于 unplugin 的自动按需引入、Nuxt 集成、手动引入与 Tree Shaking，以及size/zIndex全局配置。读完本文，你将能根据项目体积、构建工具与框架形态，选择并落地最合适的 Element Plus 引入方案，同时理解这些配置在组件库源码层的实际作用机制。本文内容以仓库 docs/en-US/guide/quickstart.md 为核心骨架，并结合 packages/element-plus 的安装器源码与 config-provider 全局配置实现进行佐证。

一、引入方式总览

Element Plus 针对不同项目诉求提供了三条主流接入路径，选择的核心权衡点是打包体积与配置成本：

下面分别展开。

二、全量引入（Full Import）

如果项目对最终打包体积没有严格要求，全量引入是最省事的方案：一次app.use()注册全部组件与插件。在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')

从源码层面看，这里的默认导出并不是一个静态对象，而是一个由工厂函数生成的安装器。核心链路如下：

• packages/element-plus/index.ts 将./defaults作为默认导出，并额外导出install、version与dayjs；
• packages/element-plus/defaults.ts 调用makeInstaller([...Components, ...Plugins])，其中Components来自 packages/element-plus/component.ts，包含约 90 个组件（如ElButton、ElConfigProvider、ElTable等），Plugins来自 packages/element-plus/plugin.ts，包含ElInfiniteScroll、ElLoading、ElMessage、ElMessageBox、ElNotification与ElPopoverDirective这些以指令/命令式 API 形式提供的功能；
• packages/element-plus/make-installer.ts 中的install(app, options?)会先通过INSTALLED_KEY检查应用是否已安装（已安装则直接返回，避免重复注册），再逐个app.use(c)注册组件与插件，最后若传入了options则调用provideGlobalConfig(options, app, true)完成全局配置注入。

由此可以推断：app.use(ElementPlus)等价于一次性注册全部组件与插件；而第二个参数options正是下文「全局配置」一节中用于注入size/zIndex的入口。

Volar 支持（TypeScript 全局组件类型）

使用 Volar（Vue 官方推荐的 VS Code 语言工具）时，为了让模板中的<el-button>等组件获得完整的类型提示与校验，需要在tsconfig.json的compilerOptions.types中加入element-plus/global：

{ "compilerOptions": { // ... "types": ["element-plus/global"] } }

该类型入口对应 packages/element-plus/package.json 中exports字段声明的"./global": { "types": "./global.d.ts" }，它向编辑器注册了所有组件的全局组件类型声明，使模板内的类型检查与组件属性补全开箱即用。

三、按需引入（On-demand Import）

按需引入的核心目标：只打包实际用到的组件及其样式。Element Plus 提供了自动引入与手动引入两种实现，官方推荐优先使用自动引入。

自动引入（Auto Import，推荐）

自动引入需要两个官方生态插件配合工作：

• unplugin-vue-components：负责在模板中扫描并自动注册用到的组件；
• unplugin-auto-import：负责自动导入ElMessage、ref等以函数形式使用的 API。

先安装依赖：

::: code-group

$ npm install -D unplugin-vue-components unplugin-auto-import

$ yarn add -D unplugin-vue-components unplugin-auto-import

$ pnpm install -D unplugin-vue-components unplugin-auto-import

:::

然后在构建配置中注册插件。Vite 项目修改vite.config.ts：

import { defineConfig } from 'vite' 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: [ // ... AutoImport({ resolvers: [ElementPlusResolver()], }), Components({ resolvers: [ElementPlusResolver()], }), ], })

Webpack 项目修改webpack.config.js：

const AutoImport = require('unplugin-auto-import/webpack') const Components = require('unplugin-vue-components/webpack') const { ElementPlusResolver } = require('unplugin-vue-components/resolvers') module.exports = { // ... plugins: [ AutoImport({ resolvers: [ElementPlusResolver()], }), Components({ resolvers: [ElementPlusResolver()], }), ], }

ElementPlusResolver是两插件共用的解析器：Components用它把模板中的<el-button>解析为对element-plus的按需组件引入并附带对应样式；AutoImport用它把ElMessage、ElMessageBox等命令式 API 自动注入到当前模块。配置完成后，模板中直接书写组件标签即可，无需任何手动 import 语句，且只会打包实际用到的组件——这正是自动引入「按需」二字的实现原理。

除 Vite、Webpack 外，该方案还支持 Rollup、Vue CLI 等其他构建工具，更多配置项请参考unplugin-vue-components与unplugin-auto-import各自的官方文档。

Nuxt 集成

Nuxt 用户有更轻量的选择：只需安装官方模块@element-plus/nuxt，无需手工配置任何 unplugin。

::: code-group

$ npm install -D @element-plus/nuxt

$ yarn add -D @element-plus/nuxt

$ pnpm install -D @element-plus/nuxt

:::

然后在nuxt.config.ts中注册模块：

export default defineNuxtConfig({ modules: ['@element-plus/nuxt'], })

pnpm 用户特别注意：Element Plus 内部依赖dayjs，而dayjs不是标准的 ES Module 包。为了让其在应用启动前被正确转换为 ESM，需要配置 pnpm 提升依赖：

• 对于 pnpm 10.5.x 及更早版本，在项目根目录的.npmrc中写入：

shamefully-hoist=true node-linker=hoisted

• 对于 pnpm 10.6.x 及更新版本，改为在pnpm-workspace.yaml中配置：

shamefullyHoist: true nodeLinker: hoisted

• 备选方案：在项目中显式安装dayjs依赖：

pnpm add dayjs

这一点与 packages/element-plus/package.json 的dependencies中声明dayjs（^1.11.20）相吻合，同时index.ts也对外导出了dayjs，便于项目直接复用同一实例，避免多实例引发的日期格式化不一致问题。

手动引入（Manually Import）

Element Plus 的 ES Module 产物天然支持 Tree Shaking，因此可以只从包中引入用到的组件：

<template> <el-button>I am ElButton</el-button> </template> <script setup lang="ts"> import { ElButton } from 'element-plus' </script>

但注意：按需手动引入组件时，其样式不会自动带上。Element Plus 的样式以独立 CSS 文件形式组织（见sideEffects字段中声明的es/components/*/style/*、theme-chalk/**/*.css），因此还需要安装unplugin-element-plus插件来自动注入对应组件样式：

import { defineConfig } from 'vite' import ElementPlus from 'unplugin-element-plus/vite' export default defineConfig({ // ... plugins: [ElementPlus()], })

该插件的具体配置方式以其官方文档为准。手动引入保留了最灵活的定制空间（例如可以按需选择是否引入图标、指令），但相应地也需要你自行维护组件清单与样式引入链路。

四、Starter 模板

官方为不同技术栈提供了可直接克隆的起步模板，省去从零搭建的步骤：

• Vite 模板（element-plus-vite-starter）：适用于以 Vite 为构建工具的 Vue 3 项目；
• Nuxt 模板（element-plus-nuxt-starter）：适用于 Nuxt 项目；
• Laravel 模板（element-plus-in-laravel-starter）：适用于 Laravel + 前端工程化的全栈项目。

使用方式均为克隆模板仓库后在本地安装依赖并启动，具体命令以各模板仓库 README 为准。仓库内也提供了可参考的完整应用示例：play/app.example.vue 与 play/src，以及覆盖各类组件 SSR 场景的 ssr-testing/cases 用例目录。

五、全局配置（Global Configuration）

在注册 Element Plus 时，可以向安装器传入第二个参数options，以设置两个全局默认值：

• size：所有表单类组件的默认尺寸（如small、default、large）；
• zIndex：弹层类组件（弹窗、消息、通知等）的默认 z-index 基数，默认值为2000。

全量引入时传入配置

import { createApp } from 'vue' import ElementPlus from 'element-plus' import App from './App.vue' const app = createApp(App) app.use(ElementPlus, { size: 'small', zIndex: 3000 })

按需引入时使用 ConfigProvider

按需引入场景没有统一的app.use入口，应改用ElConfigProvider组件包裹应用根节点：

<template> <el-config-provider :size="size" :z-index="zIndex"> <app /> </el-config-provider> </template> <script setup lang="ts"> import { ElConfigProvider } from 'element-plus' const zIndex = 3000 const size = 'small' </script>

源码层面的机制佐证

size/zIndex的传递与生效，在源码中有清晰链路：

1. 安装器透传：make-installer.ts 的install在注册完所有组件后，调用provideGlobalConfig(options, app, true)将配置注入应用级 provide；
2. 配置下发：use-global-config.ts 中的provideGlobalConfig会把配置通过configProviderContextKey、localeContextKey、namespaceContextKey、zIndexContextKey、SIZE_INJECTION_KEY、emptyValuesContextKey等多个注入键下发，任何组件都能通过useGlobalConfig(key)读取；当存在多层配置时还会执行mergeConfig做浅合并（b[key] !== undefined ? b[key] : a[key]），实现子级覆盖父级；
3. zIndex 默认值：use-z-index/index.ts 定义defaultInitialZIndex = 2000，与文档所述默认值一致；同时useGlobalConfig中对zIndex做了健壮性兜底——当配置值为undefined或NaN时回退到2000（对应use-global-config.ts中的isNil(zIndex) || Number.isNaN(zIndex)判断），这也被 config-provider 的测试用例 覆盖（包括zIndex={0}被正确尊重、NaN回退默认值等边界场景）；
4. 弹层递增：useZIndex的nextZIndex()会基于initialZIndex递增返回，保证连续弹出的多个弹层 z-index 互不重叠（如测试中配置zIndex={10000}后遮罩层得到10001）。

除size、zIndex外，ElConfigProvider还支持locale（国际化语言包）、namespace（CSS 类名前缀，默认el）、message（Message 全局配置，默认placement: 'top'，见 config-provider.ts）、button、card、dialog、link、table、a11y、keyboardNavigation、emptyValues/valueOnClear等配置项，完整声明见 config-provider-props.ts。这些能力在按需引入与全量引入两种模式下均可通过ElConfigProvider使用。

六、版本与运行环境前提

接入前请确认环境满足以下前提（依据 packages/element-plus/package.json）：

• Vue 版本：peerDependencies声明vue: ^3.3.7，即 Element Plus 面向 Vue 3 应用，请确保项目使用 Vue 3.3.7 及以上版本；
• 包入口：main指向lib/index.js（CommonJS），module指向es/index.mjs（ES Module），types指向es/index.d.ts，构建工具会按环境自动选择对应入口；
• 浏览器支持：browserslist为> 1%, not ie 11, not op_mini all，即不支持 IE 11；
• 样式入口：全量 CSS 位于element-plus/dist/index.css（对应style字段dist/index.css），按需样式则由es/components/*/style/*路径提供。

七、开始使用

完成上述任一引入方式后，即可在组件中直接使用 Element Plus。以按钮组件为例（对应组件文档 docs/en-US/component/button.md）：

<template> <el-button type="primary">Primary Button</el-button> </template>

自动引入模式下无需任何 import；全量引入模式下组件已全局注册；手动引入模式下需自行import { ElButton } from 'element-plus'并在<script setup>中声明。其余每个组件的用法、属性与事件说明，均可在仓库的 docs/en-US/component 目录下找到对应文档，例如表格见 docs/en-US/component/table.md、表单见 docs/en-US/component/form.md。

小结

本文完整覆盖了 Element Plus 的三条接入路径及其取舍：追求简单用全量引入，兼顾体积与体验用unplugin-vue-components+unplugin-auto-import自动按需引入，Nuxt 项目直接用官方@element-plus/nuxt模块，已有 ES Module 工程体系则可用手动引入配合unplugin-element-plus补齐样式。在此基础上，通过app.use(ElementPlus, { size, zIndex })或<el-config-provider>设置全局默认配置，即可让表单尺寸与弹层层级在整个应用中保持一致。理解安装器（makeInstaller）、配置下发（provideGlobalConfig）与 z-index 递增（useZIndex）三处源码实现，也能帮助你在遇到样式缺失、配置不生效、弹层层级错乱等问题时快速定位根因。

【免费下载链接】element-plus🎉 A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus