为什么要搞自己的组件库先说说一些开发的名场面看看你有没有中招新开一个项目复制粘贴上个项目的components文件夹改改名字接着用三个项目里同一套「表格 表单」各写各的改一处要改三处用现成 UI 库吧按需加载配到怀疑人生不用吧自己从零写又太慢产品说「这里要跟 XX 项目长得一样」你发现那边早改版了根本对不齐。把共用的表格、表单、图表、布局、指令、工具函数收拢成一个库统一维护、按需引用多项目复用同一套体验和逻辑——这就是自研或二次封装组件库要解决的事。一、先搭骨架工程长什么样组件库不是 SPA而是一个「被别的项目 import 的包」。举个实际项目为例my-ui-kit/ ├── src/ │ ├── main.ts # 库的唯一起点样式、组件、指令、Composables 都从这里出去 │ ├── components/ # 按业务或功能分子目录Form、Table、Menu… │ ├── directives/ # 自定义指令复制、防抖、长按、拖拽等 │ ├── modules/ # 公共模块比如 i18n、主题 │ ├── utils/ # 纯工具函数 │ └── vite-plugin.ts # 可选给使用方用的「按需解析」插件 ├── playground/ # 本地调试用的示例项目改完库立刻能看效果 ├── dist/ # 构建产物不提交发布时只发这个 ├── locales/ # 若有多语言可随库一起发布 ├── vite.config.ts ├── package.json └── tsconfig.json入口文件main.ts干三件事样式引入 Reset、UnoCSS/Tailwind 等保证打出来的dist/style.css一份就够。统一导出组件、指令、Composables如useForm、useMenu全部export方便 使用方 按需 import。插件形态导出一个带install的对象使用方可以app.use(MyUiKit)一把梭全局注册。入口示例// 样式最先 import unocss/reset/tailwind-compat.css import virtual:uno.css // 公共模块i18n、指令安装函数等 import * as I18n from ./modules/i18n export { I18n as I18nModule } import { setupDirectives } from ./directives export { setupDirectives } // 组件表格、表单、图表、菜单等 import Table from ./components/Table/Table.vue import Form from ./components/Form/Form.vue // ... 其余组件 // 指令 import XxxDirectiveCopy from ./directives/modules/copy import XxxDirectiveDebounce from ./directives/modules/debounce // ... // 全局注册插件 export const globalPlugin { install(app) { app.component(XxxTable, Table) app.component(XxxForm, Form) // ... } } // 具名导出按需引用 友好 tree-shaking export default globalPlugin export { Table as XxxTable, Form as XxxForm, useForm, useMenu /* ... */ } export { XxxDirectiveCopy, XxxDirectiveDebounce, /* ... */ }这样使用方既可以「全量 全局注册」也可以「只 import 用到的组件和 hooks」。二、配 Vite 库模式打出「可被 import 的包」骨架有了下一步是让 Vite 把项目打成库而不是打成一个能跑的网页。2.1 基础 lib 配置在vite.config.ts里加上build.libimport { resolve } from path import pkg from ./package.json export default defineConfig({ build: { lib: { entry: resolve(__dirname, src/main.ts), name: pkg.name, // UMD 时挂到 window 上的名字 formats: [es, umd], fileName: (format) ${pkg.name}.${format}.js, }, }, })es给 Vite/Webpack/Rollup 用支持 tree-shakingumd给 script 标签或老环境兜底。一执行vite builddist/里就会出现my-ui-kit.es.js、my-ui-kit.umd.js别的项目就能import了。2.2 依赖别打包进来external 是亲兄弟组件库会用到 Vue、Element Plus、ECharts、vue-router 等——这些必须由使用方项目提供不能打进你的 bundle否则会出现「两份 Vue」「包体积爆炸」等问题。在rollupOptions里把它们 external 掉并告诉 UMD「这些模块对应的是哪个全局变量」rollupOptions: { external: [ vue, element-plus, vue-router, echarts, vue-echarts, vueuse/core, vue-i18n, // 若库里会 import 自己的子路径如 locales也要写进来避免被打进 bundle my-ui-kit/locales/zh-cn.json, my-ui-kit/locales/en.json, ], output: { globals: { vue: Vue, element-plus: ElementPlus, vue-router: VueRouter, echarts: echarts, vue-echarts: VueEcharts, vue-i18n: VueI18n, }, exports: named, // 具名导出方便 tree-shaking }, }这样打出来的库又小又干净运行时和业务项目共用同一套依赖快去试试吧三、配 package.json告诉 npm「入口在哪、发布什么」3.1 主入口与类型{ name: my-ui-kit, version: 1.0.0, private: false, main: ./dist/my-ui-kit.es.js, module: ./dist/my-ui-kit.es.js, types: ./dist/index.d.ts, type: module }main / module分别给 require 和 import 用若只发 ESM可都指到 es 产物。typesTS 声明入口。3.2 使用 exports 一把梭用exports可以精细控制「主入口、样式、多语言、Vite 插件」等子路径{ exports: { .: { types: ./dist/index.d.ts, import: ./dist/my-ui-kit.es.js, require: ./dist/my-ui-kit.umd.js }, ./style: ./dist/style.css, ./dist/style.css: ./dist/style.css, ./locales/*: ./dist/locales/*, ./vite: { types: ./dist/vite-plugin.d.ts, import: ./dist/vite-plugin.js, require: ./dist/vite-plugin.cjs } } }这样使用方可以import X from my-ui-kit→ 主包import my-ui-kit/style→ 样式import zh from my-ui-kit/locales/zh-cn.json→ 多语言import { XxxComponentsResolver } from my-ui-kit/vite→ 按需解析插件若你提供了。3.3 只发 dist依赖交给使用方{ files: [dist], peerDependencies: { vue: ^3.3.11, element-plus: ^2.4.4 } }files只把dist发上去源码、playground、测试都不发。peerDependencies声明「我依赖这些但请您自己装嘞」避免重复安装、版本打架等问题。四、TypeScript 类型让用你库的人也有提示源码是.ts/.vue构建出来是.js使用方在 TS 项目里要类型提示和类型检查就得有一份.d.ts。vite-plugin-dts会在 build 时根据源码自动生成声明文件import dts from vite-plugin-dts export default defineConfig({ plugins: [ dts({ rollupTypes: true, // 把零散的 .d.ts 滚成少量文件发布更清爽 }), ], build: { /* ... */ }, })构建完dist/里会有index.d.ts等使用方装你的包就能自动获得类型补全。五、样式与静态资源别漏了 CSS 和 locales样式在main.ts最上面引入 UnoCSS/Reset 等构建后会生成dist/style.css。在package.json的exports里暴露./style使用方import my-ui-kit/style即可。多语言 / 静态资源若库内用到了locales/zh-cn.json等构建时要把它们拷到dist否则发布后引用会 404。用rollup-plugin-copy在writeBundle阶段拷贝import copy from rollup-plugin-copy plugins: [ copy({ targets: [{ src: ./locales, dest: dist/ }], hook: writeBundle, }), ]记得在exports里加上./locales/*: ./dist/locales/*使用方才能正确引用。六、构建脚本与体积分析构建和包信息都齐了接下来把日常用的脚本配好顺带加个体积分析避免悄悄打进不该打的东西。先类型检查再构建避免带着类型错误发布。例如build: run-p type-check \build-only\ --build-only里只跑vite build。体积分析可以用rollup-plugin-visualizer构建时生成依赖占比图import { visualizer } from rollup-plugin-visualizer const isAnalysis process.env.ANALYSIS true plugins: [ visualizer({ open: isAnalysis }), ]脚本里加一条analysis: cross-env ANALYSIStrue npm run build-only需要时跑一下可以心里有数。七、本地联调不发布也能在业务项目里用在真正发 npm 之前先用link在业务项目里跑一跑确保装包、引用、样式、类型都没问题。在组件库目录pnpm build pnpm link --global在业务项目目录pnpm link --global my-ui-kit之后业务项目里的import ... from my-ui-kit会直接指向你本地的dist。改完库再执行一次pnpm build刷新页面就能看到效果——再也不用手动拷 dist 了但是吧这个地方还是会有缓存问题没辙。八、按需引入既省心又省体积全量app.use(MyUiKit)会把所有组件都打进 bundle更推荐按需引用让打包器帮你 tree-shake 掉没用的。8.1 使用方自己按需 importimport { XxxTable, XxxForm, useForm } from my-ui-kit import my-ui-kit/style只要库是 ES Module 具名导出未用到的组件会被自然摇掉。8.2 自动按需unplugin-vue-components 自定义 Resolver如果希望使用方不用手写 import直接在模板里写XxxTable /就自动从库里拉对应组件可以给unplugin-vue-components提供一个自定义 Resolver。做法是在库里导出一份「组件名 → 从哪个包、用什么名字引入」的规则。例如在库的src/vite-plugin.ts里包名、前缀已泛化import { ComponentResolver } from unplugin-vue-components/types // 可选Composables 自动从库里引入避免使用方到处写 import export const XxxAutoImports { my-ui-kit: [useForm, useMenu, useDrag] } export const XxxComponentsResolver [ { type: component, resolve: (componentName) { if (componentName.startsWith(Xxx)) return { name: componentName, from: my-ui-kit } }, }, { type: directive, resolve: (name) { const map { Copy: { importName: XxxDirectiveCopy }, Debounce: { importName: XxxDirectiveDebounce }, Draggable: { importName: XxxDirectiveDraggable }, WaterMarker: { importName: XxxDirectiveWaterMarker }, // ... } const item map[name] if (!item) return return { name: item.importName, from: my-ui-kit } }, }, ]使用方在vite.config.ts里import Components from unplugin-vue-components/vite import { XxxComponentsResolver } from my-ui-kit/vite export default defineConfig({ plugins: [ Components({ resolvers: [XxxComponentsResolver], }), ], })这样模板里用到的Xxx*组件和指令都会自动按需从my-ui-kit引入。注意样式通常还是整份引入一次my-ui-kit/style即可。九、发布到 npm类型、构建、package.json、本地 link 都验证过了就可以发版了版本号npm version patch或改package.json里的version。登录npm login私有 registry 就按你们流程来。发布npm publish。若是 scoped 包且首次发记得npm publish --access public。发完别人就能pnpm add my-ui-kit然后愉快地使用啦。总结把业务中积累的「components」 抽成公共包从「复制粘贴」升级成「库模式构建 类型 规范发布 按需使用」在多项目里复用同一套组件和指令就会稳很多。组件再也不是拖累而是资源宝库后面还可以加上单元测试、文档站如 VitePress、Changelog 和语义化版本等等一步步做成团队级的组件库产品。有坑一起踩与掘友们共勉