从 0 搭建现代前端组件库：2026年完整实战指南

前言很多前端工程师用过 Element Plus、Ant Design但自己动手搭建组件库时却无从下手。本文从零开始带你搭建一个生产级组件库包含设计系统、工程化、文档、发布全流程。正文一、组件库架构设计1.1 整体架构my-ui/ ├── packages/ │ ├── components/ # 组件源码 │ ├── theme/ # 样式主题 │ └── utils/ # 工具函数 ├── docs/ # 文档站点 ├── play/ # 调试 playground ├── scripts/ # 构建脚本 └── package.json1.2 技术选型2026年标准环节工具说明构建Rollup Vite支持 ESM/CJS/UMD测试Vitest单元测试文档Storybook组件展示类型TypeScript类型定义样式SCSS CSS Vars主题定制发布Changeset版本管理二、组件设计与实现2.1 Button 组件示例// packages/components/button/src/button.tsximport{defineComponent,PropType}fromvueexportdefaultdefineComponent({name:MyButton,props:{type:{type:StringasPropTypeprimary|success|warning|danger,default:primary},size:{type:StringasPropTypesmall|medium|large,default:medium},disabled:Boolean,loading:Boolean},setup(props,{slots,emit}){return()(buttonclass{[my-button,my-button--${props.type},my-button--${props.size},{is-disabled:props.disabled,is-loading:props.loading}]}disabled{props.disabled||props.loading}onClick{()emit(click)}{props.loadingspanclassmy-button__loading/}{slots.default?.()}/button)}})2.2 样式设计CSS 变量方案// packages/theme/src/button.scss :root { --my-button-primary-bg: #409eff; --my-button-primary-text: #ffffff; --my-button-success-bg: #67c23a; --my-button-danger-bg: #f56c6c; --my-button-small-padding: 8px 12px; --my-button-medium-padding: 12px 20px; --my-button-large-padding: 16px 24px; } .my-button { display: inline-flex; align-items: center; justify-content: center; border: none; border-radius: 4px; cursor: pointer; transition: all 0.3s; --primary { background: var(--my-button-primary-bg); color: var(--my-button-primary-text); :hover { opacity: 0.8; } } --small { padding: var(--my-button-small-padding); font-size: 12px; } --medium { padding: var(--my-button-medium-padding); font-size: 14px; } }2.3 类型定义文件// packages/components/button/src/button.d.tsexporttypeButtonTypeprimary|success|warning|dangerexporttypeButtonSizesmall|medium|largeexportinterfaceButtonProps{type?:ButtonType size?:ButtonSize disabled?:booleanloading?:boolean}exportinterfaceButtonEmits{(e:click):void}三、工程化配置3.1 Rollup 构建配置// scripts/rollup.config.jsimport{defineConfig}fromrollupimportvuefromvitejs/plugin-vueimporttypescriptfromrollup/plugin-typescriptimportpostcssfromrollup-plugin-postcssimport{terser}fromrollup-plugin-terserexportdefaultdefineConfig([// ESM 构建{input:packages/components/index.ts,output:{file:dist/es/index.js,format:es},plugins:[vue(),typescript(),postcss({extract:true,minimize:true})],external:[vue]},// CJS 构建{input:packages/components/index.ts,output:{file:dist/lib/index.js,format:cjs},plugins:[vue(),typescript()],external:[vue]},// UMD 构建浏览器直接用{input:packages/components/index.ts,output:{file:dist/dist/index.full.js,format:umd,name:MyUI,globals:{vue:Vue}},plugins:[vue(),typescript(),terser()],external:[vue]}])3.2 package.json 配置{name:my-org/ui,version:0.1.0,type:module,main:dist/lib/index.js,module:dist/es/index.js,types:dist/types/index.d.ts,files:[dist,README.md],scripts:{build:rollup -c scripts/rollup.config.js,build:types:tsc --declaration --emitDeclarationOnly --outDir dist/types,test:vitest,docs:dev:storybook dev -p 6006,docs:build:storybook build -o docs-dist,release:changeset publish},peerDependencies:{vue:^3.3.0}}四、测试策略4.1 单元测试Vitest// packages/components/button/__tests__/button.spec.tsimport{describe,it,expect}fromvitestimport{mount}fromvue/test-utilsimportButtonfrom../src/buttondescribe(Button,(){it(renders correctly,(){constwrappermount(Button,{slots:{default:Click me}})expect(wrapper.text()).toBe(Click me)expect(wrapper.classes()).toContain(my-button)})it(handles different types,(){constwrappermount(Button,{props:{type:success}})expect(wrapper.classes()).toContain(my-button--success)})it(emits click event,async(){constwrappermount(Button)awaitwrapper.trigger(click)expect(wrapper.emitted()).toHaveProperty(click)})it(is disabled when loading,(){constwrappermount(Button,{props:{loading:true}})expect(wrapper.attributes(disabled)).toBeDefined()})})4.2 视觉回归测试Storybook Chromatic// packages/components/button/src/button.stories.tsimporttype{Meta,StoryObj}fromstorybook/vue3importButtonfrom./buttonconstmeta:MetatypeofButton{title:Components/Button,component:Button,argTypes:{type:{control:select,options:[primary,success,warning,danger]},size:{control:select,options:[small,medium,large]}}}exportdefaultmetatypeStoryStoryObjtypeofButtonexportconstPrimary:Story{args:{type:primary,default:Primary Button}}exportconstLoading:Story{args:{loading:true,default:Loading...}}五、文档站点搭建5.1 VitePress 配置// docs/.vitepress/config.tsimport{defineConfig}fromvitepressexportdefaultdefineConfig({title:My UI,description:A Vue 3 Component Library,themeConfig:{nav:[{text:Guide,link:/guide/},{text:Components,link:/components/}],sidebar:{/components/:[{text:Basic,items:[{text:Button,link:/components/button},{text:Icon,link:/components/icon}]},{text:Form,items:[{text:Input,link:/components/input},{text:Select,link:/components/select}]}]}}})六、发布与版本管理6.1 Changeset 配置// .changeset/config.json{$schema:https://unpkg.com/changesets/config2.3.1/schema.json,changelog:changesets/cli/changelog,commit:false,fixed:[],linked:[],access:public,baseBranch:main,updateInternalDependencies:patch,ignore:[]}6.2 发布流程# 1. 添加 changesetnpx changeset# 2. 提升版本npx changeset version# 3. 构建npmrun build# 4. 发布npx changeset publish七、设计系统对接7.1 Figma Tokens 同步// scripts/sync-figma-tokens.jsimport{getFigmaFile}fromfigma-apiasyncfunctionsyncTokens(){constfileawaitgetFigmaFile(FILE_KEY)consttokensextractTokens(file)// 生成 CSS 变量generateCSSVariables(tokens)// 生成 TypeScript 类型generateTSTypes(tokens)}八、总结搭建组件库不是简单的代码堆砌而是系统工程设计先行- 有完整的设计系统和规范质量保障- 测试覆盖、类型完整开发体验- 文档完善、调试方便发布流程- 自动化、版本管理2026年组件库新趋势AI 辅助设计Figma AI 生成组件Headless UI 模式逻辑与样式分离微前端适配Module Federation 支持