“Vue 3 组件库业务项目只用了 3 个组件结果打包完多出 1.2MB 死代码。”当你从构建日志里看到这个数字时第一反应往往是怀疑自己配置错了第二反应才是回头检查入口文件。事实上在 Vue 3 业务项目里app.use(完整组件库)是一个非常容易踩中的体积陷阱。很多组件库为了开箱即用会把自己包装成一个带 install 方法的插件而业务代码一旦整体注册构建工具很难判断哪些组件没有被使用于是大量组件逻辑和样式被打进最终 bundle。这篇文章会以 Vue 3 Vite 的常见技术栈为例讲清楚死代码是怎么产生的怎么用构建分析工具确认问题以及如何通过手动按需导入、自动按需导入和构建配置优化解决这个问题。文章的重点不是告诉你“不要全量引入”而是把背后的 tree-shaking 机制、组件库的导出结构、样式处理方式和验证手段讲明白。这样你以后在任何业务项目里看到体积异常都能自己定位、分析和收敛而不是靠猜。1. 先搞清楚 1.2MB 死代码从哪里来1.1 全量注册的写法为什么危险先看最常见的错误写法。无论是 Element Plus、Ant Design Vue 还是 Naive UI都会在官方文档里提供一种“全量引入”的方式// src/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)这段代码看起来没有任何问题在开发阶段也确实能跑得很顺畅el-button、el-table、el-dialog拿来就用。但问题在于app.use(ElementPlus)这一句它会把组件库的整个入口模块全部执行一遍。组件库的入口模块通常长这样// element-plus 的入口简化逻辑 import { ElButton } from ./components/button import { ElTable } from ./components/table // ... 几十个组件 const components [ ElButton, ElTable, ElDialog, // ... ] const install (app) { components.forEach((component) { app.component(component.name, component) }) } export default { install }构建工具在进行 tree-shaking 时只能删除那些“确定没有被外部读取”的导出。但ElementPlus这个默认导出对象被引用了install方法又被app.use()调用而install内部遍历的components数组又是运行时构造出来的。站在打包器的视角数组里的每个组件都在运行时被访问到了它不能安全地删除任何一个否则可能影响运行结果。这就是死代码的第一层来源组件被整体注册导致打包器无法静态证明某个组件没有使用。1.2 Tree Shaking 为什么对组件库“失灵”很多人对 tree-shaking 的理解是“我不用某个组件构建工具应该会自动删掉”。这个理解不完整。Tree-shaking 确实可以删除没有引用的模块但它有一个前提模块之间必须能被静态分析并且删除某个导出不会产生副作用。以 Rollup 和 Vite 为例打包器会先扫描入口文件的import语句和调用链把模块依赖关系建出来再通过 AST 分析哪些导出被真实使用。遇到import ElementPlus from element-plus这样的代码打包器发现变量ElementPlus被传给了app.use()那它必须保留这个模块的完整执行结果。组件库入口模块执行时又会启动一串内部依赖这些依赖之间还有隐藏的副作用比如往全局 DOM 上挂样式、注册私有指令、初始化 locale 配置等。package.json里通常还有一个sideEffects字段它告诉打包器“这个包里的哪些文件在导入后会产生副作用”。如果字段配置得不够精确打包器会变得更加保守。组件库为了保证样式导入正常会在dist/index.css这类文件上声明 side effect这是合理的因为样式文件不能剪。但如果组件内部的 JS 文件也被标记为有副作用tree-shaking 就会变得很无力。{ name: element-plus, sideEffects: [ **/*.css, **/*.scss ] }这里要注意sideEffects声明成数组后非 CSS 文件会被视为“无副作用”。也就是说如果组件没有被引用理论上可以删。但前提是你没有使用整个入口模块。一旦使用了入口模块这个声明就不起作用了因为入口模块的执行本身是副作用。1.3 组件库不止有组件还有指令和函数式调用组件库的包袱不只是几十个组件。以 Element Plus 为例它还包含指令比如v-loading、v-infinite-scroll。函数式组件调用比如ElMessage、ElMessageBox、ElNotification。中文语言包、主题变量、图标库。组件内部依赖的工具方法。全量注册时这些内容即使你一次都没用过也会全部被打包进去。有些函数式组件还依赖popperjs/core这类第三方库因此包体积会被进一步放大。这里有一个容易混淆的点函数式调用并不需要注册组件。很多人以为只要用了app.use(ElementPlus)ElMessage就一定能全局可用。这个理解对了一半。ElMessage在 JS 里是以模块导出的形式存在你全量引入了入口模块它自然可用但当你改成按需导入后如果不单独引入ElMessage的 JS 和样式程序运行时会直接报错。这个坑后面专门展开讲。2. 用构建分析工具确认问题不要靠猜2.1 先建立可复现的基准环境分析体积问题之前先准备一个最小可复现项目。这里不使用 Vue CLI因为现在新项目基本都用 Vite而且 Vite 的构建链路基于 Rollup分析结果更直观。npm create vuelatest vue-bundle-check # 选择 Vue Router、Pinia 等按需组合不需要的不要勾选 cd vue-bundle-check npm install element-plus项目创建完成后在main.ts里临时加入全量引入并随便在页面里使用 3 个组件。为了保证对比有效业务代码里只使用ElButton、ElDialog、ElInput这三个组件。!-- src/App.vue -- template div classpage el-button typeprimary clickvisible true 打开弹窗 /el-button el-input v-modelname placeholder请输入名称 / el-dialog v-modelvisible title示例弹窗 p当前输入{{ name }}/p /el-dialog /div /template script setup langts import { ref } from vue const visible ref(false) const name ref() /script先执行一次全量引入的构建记录产物体积npm run buildVite 默认会在命令行输出构建结果包括每个 chunk 的大小。全量引入时element-plus可能和其他依赖一起被打进一个较大的 chunk或者被拆成多个异步 chunk取决于组件库内部是否做了动态导入处理。2.2 使用 rollup-plugin-visualizer 生成体积报告命令行输出只能看到大致体积看不到具体是哪个模块占了空间。这时需要可视化分析插件。npm install -D rollup-plugin-visualizer修改vite.config.tsimport { defineConfig } from vite import vue from vitejs/plugin-vue import { visualizer } from rollup-plugin-visualizer export default defineConfig({ plugins: [ vue(), visualizer({ filename: dist/report.html, open: true, gzipSize: true, brotliSize: true }) ] })重新执行npm run build构建结束后会自动打开dist/report.html。在这个页面里你可以看到一张模块占比的矩形图。点击element-plus相关节点可以看到它锁定了哪些组件文件。从实践中看全量引入后报告里最显眼的几块通常是element-plus/es/components/table相关代码。element-plus/es/components/form、input-number、select等组件。popperjs/core。lodash-es或vue的部分工具方法。这些组件你并没有在业务代码里使用但它们通过入口模块的执行链被全部拉进来了。2.3 如何读懂构建报告体积分析报告的常见指标如下指标含义判断方法dist 总大小所有静态资源未压缩前大小对比优化前后变化gzip 大小HTTP 传输时 gzip 压缩后大小线上实际传输体积参考brotli 大小Brotli 压缩后大小现代浏览器常见传输体积参考chunk 数量拆包数量数量不是越少越好要关注重复内容某模块占比单个 npm 包在产物中的占比查找异常大的包要注意的一个细节是gzip 大小和源文件大小不是一回事。组件库代码虽然占 1.2MB但 gzip 后可能只有 300KB。很多同学看到 gzip 后体积不大就忽略问题但如果你的页面需要在前端执行解析、构建 DOM、初始化组件实例源文件大小仍然会影响长任务耗时和内存占用。死代码不只是下载成本也是执行成本。3. 两种按需引入方案把死代码从包里拿掉3.1 方案一手动按需导入组件最稳妥、最可控的方式是手动导入需要使用的组件然后局部注册。以 Vue 3 的script setup为例直接导入组件后模板中就能使用对应标签。// src/main.ts import { createApp } from vue import App from ./App.vue import { ElButton, ElDialog, ElInput } from element-plus import element-plus/es/components/button/style/css import element-plus/es/components/dialog/style/css import element-plus/es/components/input/style/css const app createApp(App) app.use(ElButton) app.use(ElDialog) app.use(ElInput) app.mount(#app)这里有三点需要解释从element-plus入口导入ElButton时打包器只保留被使用的导出理论上其它组件会被 tree-shaking 掉。样式文件要单独引入。element-plus/es/components/button/style/css是组件的样式入口。如果只导入组件 JS不导入样式界面上会出现按钮无样式、弹窗布局错乱的问题。app.use(ElButton)会注册组件为全局组件。如果项目里不允许全局注册也可以在页面级组件中导入script setup langts import { ElButton, ElInput } from element-plus import element-plus/es/components/button/style/css import element-plus/es/components/input/style/css /script template div classpage el-button typeprimary保存/el-button el-input placeholder请输入 / /div /template手动按需导入的优点是完全透明你能清楚知道每个组件来自哪里、样式是否引入。缺点是维护成本高每增加一个组件都要重复写导入语句很容易漏掉样式文件。3.2 方案二使用 unplugin-vue-components 自动按需导入实际项目中更推荐自动按需导入。unplugin-vue-components是一个构建期插件它会扫描模板中使用到的组件标签自动把对应的组件模块和样式加进 bundle。npm install -D unplugin-vue-components npm install unplugin-auto-import修改vite.config.tsimport { defineConfig } from vite import vue from vitejs/plugin-vue import Components from unplugin-vue-components/vite import AutoImport from unplugin-auto-import/vite import { ElementPlusResolver } from unplugin-vue-components/resolvers export default defineConfig({ plugins: [ vue(), Components({ resolvers: [ElementPlusResolver()], dts: src/components.d.ts }), AutoImport({ resolvers: [ElementPlusResolver()], dts: src/auto-imports.d.ts }) ] })此时main.ts里不需要再写app.use(ElementPlus)也不需要手动引入组件样式。插件在构建时扫描App.vue和其它.vue文件发现模板里有el-button、el-dialog、el-input就会自动导入这三个组件和对应样式。自动导入的产物结构和手动导入基本一致但它需要在构建时扫描全项目模板。这里有一个容易忽略的点只有模板中出现的组件才被自动导入。如果你在 JS 里写h(ElButton, ...)或者markRaw(SomeComponent)插件无法识别此时还是要手动 import。3.3 函数式组件的特殊处理ElMessage、ElMessageBox、ElNotification这类函数式调用不在模板里出现unplugin-vue-components无法自动处理。它们由unplugin-auto-import负责可以自动导入 API 名称但样式需要额外处理。一种常见做法是全局只引入函数式组件的样式// src/main.ts import element-plus/es/components/message/style/css import element-plus/es/components/message-box/style/css import element-plus/es/components/notification/style/css或者使用ElementPlusResolver的配置项ElementPlusResolver({ importStyle: css, directives: true, version: 2.x })directives: true是为了支持v-loading这类指令。自动导入插件默认只处理组件不使用配置时指令不会被自动注册页面控制台会出现Failed to resolve directive: loading的警告。4. 配置验证对比打包产物确认效果可量化4.1 同一份业务代码三种引入方式为了对比公平仍然使用前面那 3 个组件。这里分别用三种方式构建引入方式main.ts 核心代码预期产物全量引入app.use(ElementPlus)体积最大手动按需单独导入 3 个组件体积明显减小自动按需插件自动处理与手动按需接近手动按需的main.ts简化为import { createApp } from vue import App from ./App.vue createApp(App).mount(#app)组件在页面级导入script setup langts import { ElButton, ElInput } from element-plus import { ElDialog } from element-plus import element-plus/es/components/button/style/css import element-plus/es/components/input/style/css import element-plus/es/components/dialog/style/css /script自动按需的main.ts同样保持干净组件由插件自动注入。4.2 构建输出的对比构建后可以对比dist目录的大小。这里给出一个典型的观察顺序记录全量构建的dist/assets下所有 JS 文件大小之和。记录手动按需构建后的总和。记录自动按需构建后的总和。如果项目只用了 3 个组件全量引入时多出的 1.2MB 主要来自未使用的组件代码和样式。按需引入后这个体积通常会降到几百 KB 以内。具体数值和组件库版本、构建配置、是否开启 gzip 有关不建议死记数值要看相对变化。为了排查准确可以在vite.config.ts中开启build.rollupOptions.output.manualChunks把element-plus单独拆成一个 chunk便于观察export default defineConfig({ build: { rollupOptions: { output: { manualChunks: { element-plus: [element-plus] } } } } })注意手动拆包后全量引入时 chunk 会很大按需引入时这个手动配置反而可能让三个组件也构成一个 chunk。这个配置只适合临时观察不适合作为最终上线方案。上线时如果为了缓存可以单独拆 vendor但要基于新的体积报告重新设计不要照搬。4.3 在浏览器里检查产物防止“看起来变小了实际还是全量”构建体积报告是开发侧的判断依据线上环境还需要一条更直接的验证手段。打开线上页面按 F12 进入 DevTools切到 Sources 面板在dist/assets目录里搜索el-table或ElTable等未使用组件的特征字符串。如果搜索结果里出现大量相关代码说明该组件还是被打进了产物。搜索el-select、el-date-picker也是同样的思路。也可以搜索组件库特有但你不使用的组件名比如ElTreeSelect、ElCascader等。这里要注意不要只搜组件名。打包器会对变量名做压缩重命名类名、方法名和字符串不一定保留原始命名。更稳妥的方式是搜索组件库内部一些固定字符串比如 Element Plus 里的ElTable组件内部会包含el-table的 class 名但压缩后仍然会保留字符串。如果字符串不存在基本可以断定该组件未被打入产物。5. 遗留问题和常见坑5.1 动态组件:is导致组件被误删模板中使用component :iscurrentComponent /时自动导入插件无法在构建期确定currentComponent的具体值。运行时如果传入el-table这类字符串组件没有提前注册页面会渲染失败。处理方式有两种。第一种是在当前页面显式导入并注册可能用到的组件script setup langts import { ElTable } from element-plus import element-plus/es/components/table/style/css /script第二种是把组件放入一个对象映射中import { ElTable, ElDialog } from element-plus const componentMap { table: ElTable, dialog: ElDialog }这种做法在表单设计器、页面配置化渲染等场景很常见。关键是让组件以变量引用的方式出现这样打包器能静态识别。5.2 指令没有自动注册v-loading、v-infinite-scroll是组件库提供的指令unplugin-vue-components默认不注册指令。如果项目大量使用了v-loading建议在main.ts里手动导入指令import { ElLoading } from element-plus const app createApp(App) app.directive(loading, ElLoading.directive)另一个方案是在AutoImport插件里配置ElementPlusResolver({ directives: true })。但实际经验是指令的自动识别容易出现误判尤其当指令名被包装或重命名时手动注册更可控。5.3 样式重复引入和主题定制失败按需导入后常遇到两个样式问题。第一个是样式重复。如果页面里手动导入了组件样式而某个全局样式文件又引入了完整主题 CSS最终构建产物里会出现两份相同规则线上样式可能被覆盖。排查方式是搜索构建后的 CSS 文件看是否有重复的按钮、弹窗、输入框规则。第二个是主题变量失效。Element Plus 2.x 使用 SCSS 变量做主题定制按需导入style/css时引入的是编译后的 CSS变量定制无法生效。如果项目需要改主题色应该引入style/index或者通过unplugin-element-plus插件处理同时保证全局有自定义的 SCSS 变量。// 定制主题时引入的样式路径示例 forward element-plus/theme-chalk/src/common/var.scss with ( $colors: ( primary: ( base: #409eff ) ) );5.4 图标库体积容易被忽略组件库死代码清理完后最常见的新增体积来源是图标库。很多人从组件库导出ElIcon又把所有图标组件import * as Icons from element-plus/icons-vue然后全局注册这等于制造了一个新的全量引入。正确用法是单个导入图标import { Plus, Delete } from element-plus/icons-vue const app createApp(App) app.component(Plus, Plus) app.component(Delete, Delete)或者保持本地引用不注册为全局组件。5.5 版本升级导致按需路径失效组件库升级后组件文件路径可能变化。比如 Element Plus 从 1.x 到 2.xelement-plus/lib/和element-plus/es/的目录结构不一样。手动按需导入时最好直接依赖官方文档提供的路径不要拼接内部目录。如果使用unplugin-vue-components建议锁定插件和组件库的大版本避免解析器与组件库内部导出结构不兼容。出现找不到模块、样式缺失等问题时先确认两边的版本是否匹配。6. 组件库选型与工程化落地建议6.1 从组件库角度看 tree-shaking 支持不同组件库对 tree-shaking 的支持程度不同。选型时可以从三个维度看维度判断方式是否提供 ESM 模块看package.json的module字段和dist下是否有.mjs文件是否声明sideEffects看package.json是否对样式和非样式文件做了区分是否提供自动导入 resolver官方文档是否支持unplugin-vue-components的 resolverElement Plus、Ant Design Vue、Naive UI 等主流组件库都支持 ESM 和自动导入。但支持方式和位置不同。Ant Design Vue 的自动导入通常也需要unplugin-vue-components配合AntDesignVueResolver。Naive UI 本身支持 tree-shaking 较好因为它的组件导出结构就是按模块拆分的。选型时不要只看可用的组件数量也要看构建产物形态。6.2 从项目角度看如何避免死代码扩散组件库只是死代码的来源之一。进入生产维护期后业务代码也可能出现类似问题。在项目实践中建议把下面几条作为固定检查项禁止在入口文件使用app.use(整个组件库)除非项目确实使用了大多数组件。封装统一的ui.ts或components/index.ts集中管理组件导入和注册不要让每个页面各自写一套导入方式。图标按需导入不要循环注册。工具函数库同样采用按需导入比如lodash-es。新依赖加入前先跑一次npm run build对比构建体积是否异常增长。6.3 项目里的可复用检查清单以下清单可以直接用于发版前检查1. 入口文件是否存在全量引入组件库的代码 2. 是否存在 import * as XXX from 组件库 的写法 3. 模板中是否只使用了少量组件但 bundle 里出现大量组件库特征字符串 4. 函数式组件Message/Notification/MessageBox的样式是否单独引入 5. 指令v-loading 等是否注册成功 6. 单页应用是否按路由拆分了 chunk 7. 项目是否开启了 gzip 或 Brotli 8. 图标是否按需导入 9. 是否存在重复引入完整样式的问题 10. 每次依赖升级后是否重新对比产物体积报告把这套清单固化到项目的 MR 流程或发布脚本里能有效防止死代码在后续迭代中重新回来。6.4 值得进一步的优化方向解决 1.2MB 死代码只是开始。清掉死代码后还可以沿着下面几个方向继续优化路由级代码分割。Vue Router 配置改为动态 import按需加载页面模块。第三方依赖拆包和长期缓存策略。把不变依赖放入vendorchunk合理设置maxSize和缓存组。组件内部再次拆分。如果某个复杂表格组件只在若干页面使用可考虑异步加载或延迟渲染。使用defineAsyncComponent对低频业务组件做异步注册减少首屏 bundle。这些优化的核心原则是一致的让打包器能静态判断哪些代码不需要让运行时只加载当前场景必要的内容。组件库按需导入是第一步也是最容易见效的一步。先把入口文件里那行全量注册改掉再配合体积分析报告持续观察前端产物体积失控的问题才会真正被控制住。