组件库从0到1搭建实践从第一个按钮到发布到npm的完整流程前几个月在做一个跨多个业务线的中后台项目群技术栈统一是Vue 3 TypeScript。一开始各团队各自为战几个项目里光按钮组件就有三种写法表格分页更是各玩各的。跟几个前端负责人聊了一圈决定停下来搞一套内部组件库。从技术选型、目录设计到第一条命令跑通再到按需引入、构建产物配置、发布npm私有包整个过程走了不少弯路。这篇就把这套从0到1的完整流程梳理出来重点讲清楚每一步为什么这么做以及我在实操中踩过的坑和验证过的经验。如果你正准备在团队里搭组件库或者毕业设计需要一个有说服力的前端项目这篇内容可以直接参考。1. 设计思路与整体方案选型1.1 为什么用Vue 3 TS Vite这套组合选技术栈的时候其实纠结过一阵。团队现有项目是Vue 2为主但新项目已经全面切到Vue 3加上组合式API写起来确实利索最终定了Vue 3。TypeScript没有犹豫组件库的props、emits、slots类型定义清楚之后业务方使用时的智能提示能省掉大量查文档的时间。Vite做构建工具在开发体验上明显优于Webpack组件库本身对ESM和Tree-Shaking的支持也更友好按需引入配合起来非常顺手。有一点需要注意组件库的代码质量要比业务代码更严格。业务代码里偶尔的any还能容忍组件库里的类型不写清楚下游开发根本不敢用。我们当时约定组件props和emits必须导出完整类型方法重载必须写明确不允许在对外接口里出现any。1.2 Monorepo还是单包根据团队规模做选择这是第二个关键决策。Monorepo比如pnpm workspace适合多包管理比如组件库加工具函数库加文档站三个包独立发版。我们团队当时只有三个前端维护多包的成本高于收益最终选择了单包结构组件、样式、类型、工具函数都在一个包内文档站单独放在docs/目录但不参与发布。如果你计划把工具函数、UI组件、业务组件拆成多个独立包发布那直接上pnpm workspace一步到位比后面拆包省事得多。组件库单包的结构大致长这样├── docs/ # 文档站源码 ├── packages/ # 组件源码目录 │ ├── button/ │ │ ├── src/ │ │ │ ├── button.tsx │ │ │ └── types.ts │ │ ├── style/ │ │ └── index.ts │ └── ... ├── src/ │ ├── index.ts # 统一出口 │ └── style/ ├── vite.config.ts ├── package.json └── tsconfig.json1.3 样式方案CSS变量 SCSS混合使用样式方案我们用了CSS变量加SCSS。全局主题色、圆角、字体、间距全部用CSS变量定义在:root下这样业务方可以通过覆盖变量的方式做简易换肤。组件内部复杂样式用SCSS编写编译产物导出CSS变量引用避免把具体色值写死在组件里。这个选择的直接后果是后续做暗色模式或者主题定制时只需要在业务侧重新定义一组变量值就行组件代码完全不用动。2. 核心细节解析与实操要点2.1 组件API设计参考成熟组件库做减法组件API设计是组件库最见功底的部分。我的建议是直接参考Element Plus这类成熟库的API结构然后做减法。以Button为例第一版只保留type、size、disabled、loading、onClick几个核心属性其它花哨的比如round、circle、tag全部不加。原因很简单组件第一版的目标是让业务先跑起来后续按需新增反而是个持续迭代的节奏一开始塞满API容易把自己绕晕。每个组件对外暴露的能力分为四块props组件的输入参数必须定义默认值。emits组件对外的事件统一用emit(update:modelValue, val)这类受控模式。slots插槽用于定制组件内部内容比如prefix、suffix、default。expose通过defineExpose暴露的方法或状态比如formRef.validate()。2.2 命名规范与目录约定组件目录名统一使用全小写kebab-case如button、input-number。组件文件命名使用PascalCase如Button.tsx。样式文件与组件同目录放在style/子文件夹里。这样每个组件目录自包含新增一个组件就是新建一个文件夹删除也是直接删文件夹操作成本极低。我踩过的坑是组件导出时createVNode和h函数混用导致类型推断失效。后来统一约定代码里只用h函数创建虚拟节点关闭createVNode的使用类型提示才恢复正常。2.3 环境准备与基础工程配置在动手写组件之前先花半小时把工程骨架搭好。我用的基础模板是vite的vue-ts模板装好依赖后手动调整tsconfig.json{ compilerOptions: { target: ES2020, module: ESNext, moduleResolution: bundler, strict: true, jsx: preserve, resolveJsonModule: true, isolatedModules: true, esModuleInterop: true, lib: [ES2020, DOM, DOM.Iterable], skipLibCheck: true, baseUrl: ., paths: { /*: [packages/*] } } }你会发现没有设置outDir和declaration因为组件库的产出物不需要通过tsc编译生成Vite构建会帮我们干这件事。declaration交给vite-plugin-dts插件处理这比tsc生成顺滑得多。2.4 安装依赖与版本锁定依赖全部锁定精确版本不用^或~前缀。原因很简单组件库的每个发布版本必须可复现如果依赖浮动上次构建和下次构建的产物体积、行为可能不一致问题排查起来极其痛苦。在package.json里直接写具体版本号锁文件提交到仓库后续升级依赖用pnpm update显式操作。3. 按需引入机制与全量引入实现3.1 全量引入最简单直接的方式全量引入就是提供一个注册入口一次性把所有组件注册到应用上。在src/index.ts里写import type { App } from vue; import Button from ../packages/button; import Input from ../packages/input; import { version } from ../package.json; const components [Button, Input]; const install (app: App) { components.forEach(component { app.component(component.name, component); }); }; export default { version, install, ...components }; export { Button, Input };全量引入的优点是简单、好用直接app.use(MyUI)完事不担心漏组件。缺点是产物体积大所有组件全部打进main.js业务方二次分包约不到组件。适合内部工具类项目页面少性能压力小。3.2 按需引入核心机制与原理解析按需引入的本质是借助ES Module的静态分析能力让打包器只打包实际用到的组件。实现方式有两种主流方案方案A配合UI框架自身模块结构通过babel插件转换引入路径方案B组件库直接导出ESM格式产物业务方直接用ESM的import语句按需引入我们选了方案B产物格式为ESM业务方这样用import { Button } from my-ui; import my-ui/es/button/style/index.css;关键在于Vite构建时配置build.lib把入口指向组件库根目录产物的exports字段映射好每个组件的路径。这样就做到了按需引入组件只加载用到的样式同理。3.3 样式按需加载策略样式按需加载的策略是每个组件编译出独立的CSS文件。如果业务方只想用Button那就只引入Button的样式文件不引入Input的。实现上在vite.config.ts里配置css.codeSplit确保组件级样式独立输出。结合vite-plugin-dts生成类型文件业务方拿到的是组件的完整信息JS逻辑加样式加类型三件套齐全。4. 新组件开发全流程以Button为例4.1 组件props设计功能边界与前向兼容以Button为例还是那句话从最小功能集开始。第一版Button的props如下export interface ButtonProps { type?: default | primary | success | warning | danger; size?: small | default | large; disabled?: boolean; loading?: boolean; nativeType?: button | submit | reset; onClick?: (event: MouseEvent) void; }为什么type默认值给default而不是primary因为大多数业务场景下按钮不是页面主角频繁出现的是默认样式按钮传个typeprimary才是主动选择。这是从设计心理学里的默认值即选择原则来的降低绝大多数场景的使用成本。4.2 Button组件实现与代码解析Button组件的核心难点不在模板而在样式和状态组合。状态组合是这类组件最容易出bug的地方loading状态必须禁用点击disabled优先级高于loading点击事件必须判断运行状态。核心代码如下template button :class[ my-button, my-button--${type}, my-button--${size}, { is-disabled: disabled || loading, is-loading: loading } ] :disableddisabled || loading :typenativeType clickhandleClick span v-ifloading classmy-button__loading-icon / slot / /button /template script setup langts defineOptions({ name: MyButton }); const props withDefaults(definePropsButtonProps(), { type: default, size: default, disabled: false, loading: false, nativeType: button }); const emit defineEmits{ click: [event: MouseEvent] }(); const handleClick (event: MouseEvent) { if (props.disabled || props.loading) return; emit(click, event); }; /script这里有个关键细节defineOptions({ name })必须写因为后续全量注册时app.component(component.name, component)依赖这个name给组件命名。4.3 组件测试的两个核心维度组件测试分两层。第一层是渲染测试用vue/test-utils加vitest验证props渲染正确性。第二层是交互测试模拟点击事件验证emit触发。script setup langts const props withDefaults(definePropsButtonProps(), { type: default, }); const emit defineEmits{ click: [event: MouseEvent] }(); const handleClick (e: MouseEvent) { if (props.disabled || props.loading) return; emit(click, e); }; /script测试用例覆盖的是边界场景比如disabled为真时点击不触发emitloading为真时class包含is-loading且点击不触发事件typedanger设置后class包含my-button--danger。这些边界在业务使用中最容易出问题。4.4 组件类型导出策略类型导出对TS项目至关重要。在packages/button/index.ts中import Button from ./src/button.vue; import type { ButtonProps } from ./src/types; import type { App } from vue; Button.install (app: App) { app.component(Button.name, Button); }; export default Button; export { ButtonProps };这样业务方就可以import { Button } from my-ui; import type { ButtonProps } from my-ui; const config: ButtonProps { type: primary, size: small };类型定义必须细到props的联合类型枚举不能全部string。用type: primary直接写字符串也能通过类型检查这就是类型带来的开发体验提升。5. 文档书写组件文档即组件演示5.1 文档站选择VitePress适配组件库展示场景文档站我们用了VitePress。为什么不用StorybookStorybook组件探索功能很强但中后台项目更需要的是一篇篇文档、API表格和在线示例。VitePress基于Vite冷启动秒开Markdown写文档天然顺手还支持Vue组件直接嵌入。5.2 文档结构模板化每个组件的文档都按固定模板写这样新开发者在找信息时不需要猜。模板包含组件名称与一句话简介功能特性列表在线演示实时可交互代码示例带源码展示API表格props、emits、slots、expose四张表使用注意与常见问题比如Button文档里的代码示例VitePress里直接写vue代码块支持右上角复制按钮读者一键复制即用。5.3 自动生成props表格手写API表格效率低且容易遗漏字段。我们用了一个小工具读ts类型定义自动生成props表格的markdown片段。这块做成脚本放docs/.vitepress/scripts/gen-props.ts写完组件类型跑一条命令表格自动更新省下大量维护文档的时间。6. 构建产物配置与发布npm6.1 Vite构建配置解析组件库的构建配置直接决定产物质量。核心配置如下import { defineConfig } from vite; import vue from vitejs/plugin-vue; import dts from vite-plugin-dts; import { resolve } from path; export default defineConfig({ plugins: [ vue(), dts({ entryRoot: packages, outDir: [dist/es, dist/lib], tsconfigPath: ./tsconfig.json, }) ], build: { lib: { entry: resolve(__dirname, src/index.ts), name: MyUI, formats: [es, umd], fileName: (format) format es ? index.js : index.umd.cjs }, rollupOptions: { external: [vue], output: { globals: { vue: Vue }, preserveModules: true, preserveModulesRoot: packages, assetFileNames: [name].[ext] } } } });external: [vue]是必需的如果不过滤vue依赖产物里会打包一份Vue运行时和业务方的Vue冲突导致运行时异常。preserveModules开启后产物会保留组件的目录结构dist/es/ ├── button/ │ ├── button.vue.js │ └── style.css ├── input/ │ ├── input.vue.js │ └── style.css └── index.js这样业务方才能精准按需加载。6.2 package.json的exports字段配置package.json里的exports字段定义了不同场景下的入口。我踩过的坑是exports配置错误导致组件库自己的类型在文档站里失效排查了半天发现是exports里类型路径写错了。{ name: my-ui, version: 0.1.0, main: ./dist/lib/index.umd.cjs, module: ./dist/es/index.js, types: ./dist/types/index.d.ts, exports: { .: { types: ./dist/types/index.d.ts, import: ./dist/es/index.js, require: ./dist/lib/index.umd.cjs }, ./es/*: ./dist/es/*, ./dist/*: ./dist/*, ./package.json: ./package.json } }exports里的es/*路径映射是给按需引入用的业务方写import my-ui/es/button/style/index.css时打包器会找到dist/es/button/style/index.css。6.3 npm发布前检查清单发布npm前必须跑一遍检查我整理了一个固定清单执行pnpm build确认构建无报错检查dist/目录产物存在且路径正确用npm pack生成本地tarball检查包内容是否包含dist和类型文件在空白Vue3项目中安装本地包验证全量引入与按需引入确认package.json中files字段包含dist和types目录检查name、version是否与上次发布冲突查看dependencies与peerDependencies是否配置得当6.4 npm发包命令与发布过程发布命令分两步先登录后发布npm login npm publish如果发布私有包用私有registry地址如npm config set registry https://npm.internal.registry/或者在.npmrc文件里配置。发布成功后在业务项目里安装npm install my-ui --save组件库默认只发布最新tag历史版本用npm publish --tag beta发布测试版本时需要指定--tag和--access参数。7. 常见问题与排查技巧实录7.1 “组件未注册”空错误排查这个错误几乎每个用组件库的人都会遇到。全量引入时报Unhandled error during execution of scheduler flush多半是注册时漏了app.use(MyUI)或者全量注册时组件不是标准组件格式没有name。先查注册入口代码确定app.use()有没有执行再确认组件defineOptions里的name是否与组件名一致。7.2 按需引入后样式丢失按需引入样式丢失是最常见的问题排查思路就一条路径检查import my-ui/es/button/style/index.css路径是否正确。如果路径对检查Vite构建的assetFileNames配置是否正确输出了CSS文件以及业务方是否配置了css相关loader。7.3 类型失效与TS报错排除方法类型失效多半是vite-plugin-dts的输出目录和package.json的types字段不一致导致TS找不到类型声明。先确认tsconfig.json里declarationDir再检查types指向的文件是否真实存在。还有一种情况是构建时dts插件输出声明文件被清空插件顺序写错造成调整dts插件放vue()之后即可。7.4 发布后版本号冲突与撤销如果发错版本号或者内容有严重bug用npm unpublish my-ui版本号 --force撤销某个版本。撤销后该版本号不能再重复使用所以发布前一定跑完整测试和构建流程优先保证质量。8. 实操心得与个人经验总结组件库从0到1看起来工作量不大实际涉及的知识面相当宽设计规范、Vue组件机制、Vite构建、类型系统、文档工程、npm发包全流程每一环都有不少隐性细节。我个人最大的收获是组件库不是代码量的积累而是工程化思维的集大成。一开始只想写几个按钮组件做到后面发现难的不是按钮样式而是让每个按钮在任何Vue3项目中都能稳定工作、类型完备、按需打包、样式可定制。这些能力的积累对日常业务开发帮助很大。如果只是做毕设或学习项目我建议先做一个完整的核心组件比如Button把全流程跑通再扩展Input、Select、Table这些常用组件。全流程跑通更重要因为面试官聊的是整体方案而不是组件数量。核心点就一个证明你对这套体系的理解深度而不是广度。最后分享一个细节技巧组件库的代码里尽量少用console.log用debugger代替或者用自定义的logger函数后续排查业务问题时会轻松很多。组件库被业务方引入后组件库里的console.log会直接打到业务的控制台影响别人调试不说有时还会混淆问题来源。这个框架后续还可以扩展接入单元测试覆盖率看板增加自定义主题配置能力或者把常用业务组件如表单弹窗、搜索面板沉淀为高阶组件。从第一个Button到完整组件库这条路值得好好走一遍。
组件库从0到1搭建实践从第一个按钮到发布到npm的完整流程前几个月在做一个跨多个业务线的中后台项目群技术栈统一是Vue 3 TypeScript。一开始各团队各自为战几个项目里光按钮组件就有三种写法表格分页更是各玩各的。跟几个前端负责人聊了一圈决定停下来搞一套内部组件库。从技术选型、目录设计到第一条命令跑通再到按需引入、构建产物配置、发布npm私有包整个过程走了不少弯路。这篇就把这套从0到1的完整流程梳理出来重点讲清楚每一步为什么这么做以及我在实操中踩过的坑和验证过的经验。如果你正准备在团队里搭组件库或者毕业设计需要一个有说服力的前端项目这篇内容可以直接参考。1. 设计思路与整体方案选型1.1 为什么用Vue 3 TS Vite这套组合选技术栈的时候其实纠结过一阵。团队现有项目是Vue 2为主但新项目已经全面切到Vue 3加上组合式API写起来确实利索最终定了Vue 3。TypeScript没有犹豫组件库的props、emits、slots类型定义清楚之后业务方使用时的智能提示能省掉大量查文档的时间。Vite做构建工具在开发体验上明显优于Webpack组件库本身对ESM和Tree-Shaking的支持也更友好按需引入配合起来非常顺手。有一点需要注意组件库的代码质量要比业务代码更严格。业务代码里偶尔的any还能容忍组件库里的类型不写清楚下游开发根本不敢用。我们当时约定组件props和emits必须导出完整类型方法重载必须写明确不允许在对外接口里出现any。1.2 Monorepo还是单包根据团队规模做选择这是第二个关键决策。Monorepo比如pnpm workspace适合多包管理比如组件库加工具函数库加文档站三个包独立发版。我们团队当时只有三个前端维护多包的成本高于收益最终选择了单包结构组件、样式、类型、工具函数都在一个包内文档站单独放在docs/目录但不参与发布。如果你计划把工具函数、UI组件、业务组件拆成多个独立包发布那直接上pnpm workspace一步到位比后面拆包省事得多。组件库单包的结构大致长这样├── docs/ # 文档站源码 ├── packages/ # 组件源码目录 │ ├── button/ │ │ ├── src/ │ │ │ ├── button.tsx │ │ │ └── types.ts │ │ ├── style/ │ │ └── index.ts │ └── ... ├── src/ │ ├── index.ts # 统一出口 │ └── style/ ├── vite.config.ts ├── package.json └── tsconfig.json1.3 样式方案CSS变量 SCSS混合使用样式方案我们用了CSS变量加SCSS。全局主题色、圆角、字体、间距全部用CSS变量定义在:root下这样业务方可以通过覆盖变量的方式做简易换肤。组件内部复杂样式用SCSS编写编译产物导出CSS变量引用避免把具体色值写死在组件里。这个选择的直接后果是后续做暗色模式或者主题定制时只需要在业务侧重新定义一组变量值就行组件代码完全不用动。2. 核心细节解析与实操要点2.1 组件API设计参考成熟组件库做减法组件API设计是组件库最见功底的部分。我的建议是直接参考Element Plus这类成熟库的API结构然后做减法。以Button为例第一版只保留type、size、disabled、loading、onClick几个核心属性其它花哨的比如round、circle、tag全部不加。原因很简单组件第一版的目标是让业务先跑起来后续按需新增反而是个持续迭代的节奏一开始塞满API容易把自己绕晕。每个组件对外暴露的能力分为四块props组件的输入参数必须定义默认值。emits组件对外的事件统一用emit(update:modelValue, val)这类受控模式。slots插槽用于定制组件内部内容比如prefix、suffix、default。expose通过defineExpose暴露的方法或状态比如formRef.validate()。2.2 命名规范与目录约定组件目录名统一使用全小写kebab-case如button、input-number。组件文件命名使用PascalCase如Button.tsx。样式文件与组件同目录放在style/子文件夹里。这样每个组件目录自包含新增一个组件就是新建一个文件夹删除也是直接删文件夹操作成本极低。我踩过的坑是组件导出时createVNode和h函数混用导致类型推断失效。后来统一约定代码里只用h函数创建虚拟节点关闭createVNode的使用类型提示才恢复正常。2.3 环境准备与基础工程配置在动手写组件之前先花半小时把工程骨架搭好。我用的基础模板是vite的vue-ts模板装好依赖后手动调整tsconfig.json{ compilerOptions: { target: ES2020, module: ESNext, moduleResolution: bundler, strict: true, jsx: preserve, resolveJsonModule: true, isolatedModules: true, esModuleInterop: true, lib: [ES2020, DOM, DOM.Iterable], skipLibCheck: true, baseUrl: ., paths: { /*: [packages/*] } } }你会发现没有设置outDir和declaration因为组件库的产出物不需要通过tsc编译生成Vite构建会帮我们干这件事。declaration交给vite-plugin-dts插件处理这比tsc生成顺滑得多。2.4 安装依赖与版本锁定依赖全部锁定精确版本不用^或~前缀。原因很简单组件库的每个发布版本必须可复现如果依赖浮动上次构建和下次构建的产物体积、行为可能不一致问题排查起来极其痛苦。在package.json里直接写具体版本号锁文件提交到仓库后续升级依赖用pnpm update显式操作。3. 按需引入机制与全量引入实现3.1 全量引入最简单直接的方式全量引入就是提供一个注册入口一次性把所有组件注册到应用上。在src/index.ts里写import type { App } from vue; import Button from ../packages/button; import Input from ../packages/input; import { version } from ../package.json; const components [Button, Input]; const install (app: App) { components.forEach(component { app.component(component.name, component); }); }; export default { version, install, ...components }; export { Button, Input };全量引入的优点是简单、好用直接app.use(MyUI)完事不担心漏组件。缺点是产物体积大所有组件全部打进main.js业务方二次分包约不到组件。适合内部工具类项目页面少性能压力小。3.2 按需引入核心机制与原理解析按需引入的本质是借助ES Module的静态分析能力让打包器只打包实际用到的组件。实现方式有两种主流方案方案A配合UI框架自身模块结构通过babel插件转换引入路径方案B组件库直接导出ESM格式产物业务方直接用ESM的import语句按需引入我们选了方案B产物格式为ESM业务方这样用import { Button } from my-ui; import my-ui/es/button/style/index.css;关键在于Vite构建时配置build.lib把入口指向组件库根目录产物的exports字段映射好每个组件的路径。这样就做到了按需引入组件只加载用到的样式同理。3.3 样式按需加载策略样式按需加载的策略是每个组件编译出独立的CSS文件。如果业务方只想用Button那就只引入Button的样式文件不引入Input的。实现上在vite.config.ts里配置css.codeSplit确保组件级样式独立输出。结合vite-plugin-dts生成类型文件业务方拿到的是组件的完整信息JS逻辑加样式加类型三件套齐全。4. 新组件开发全流程以Button为例4.1 组件props设计功能边界与前向兼容以Button为例还是那句话从最小功能集开始。第一版Button的props如下export interface ButtonProps { type?: default | primary | success | warning | danger; size?: small | default | large; disabled?: boolean; loading?: boolean; nativeType?: button | submit | reset; onClick?: (event: MouseEvent) void; }为什么type默认值给default而不是primary因为大多数业务场景下按钮不是页面主角频繁出现的是默认样式按钮传个typeprimary才是主动选择。这是从设计心理学里的默认值即选择原则来的降低绝大多数场景的使用成本。4.2 Button组件实现与代码解析Button组件的核心难点不在模板而在样式和状态组合。状态组合是这类组件最容易出bug的地方loading状态必须禁用点击disabled优先级高于loading点击事件必须判断运行状态。核心代码如下template button :class[ my-button, my-button--${type}, my-button--${size}, { is-disabled: disabled || loading, is-loading: loading } ] :disableddisabled || loading :typenativeType clickhandleClick span v-ifloading classmy-button__loading-icon / slot / /button /template script setup langts defineOptions({ name: MyButton }); const props withDefaults(definePropsButtonProps(), { type: default, size: default, disabled: false, loading: false, nativeType: button }); const emit defineEmits{ click: [event: MouseEvent] }(); const handleClick (event: MouseEvent) { if (props.disabled || props.loading) return; emit(click, event); }; /script这里有个关键细节defineOptions({ name })必须写因为后续全量注册时app.component(component.name, component)依赖这个name给组件命名。4.3 组件测试的两个核心维度组件测试分两层。第一层是渲染测试用vue/test-utils加vitest验证props渲染正确性。第二层是交互测试模拟点击事件验证emit触发。script setup langts const props withDefaults(definePropsButtonProps(), { type: default, }); const emit defineEmits{ click: [event: MouseEvent] }(); const handleClick (e: MouseEvent) { if (props.disabled || props.loading) return; emit(click, e); }; /script测试用例覆盖的是边界场景比如disabled为真时点击不触发emitloading为真时class包含is-loading且点击不触发事件typedanger设置后class包含my-button--danger。这些边界在业务使用中最容易出问题。4.4 组件类型导出策略类型导出对TS项目至关重要。在packages/button/index.ts中import Button from ./src/button.vue; import type { ButtonProps } from ./src/types; import type { App } from vue; Button.install (app: App) { app.component(Button.name, Button); }; export default Button; export { ButtonProps };这样业务方就可以import { Button } from my-ui; import type { ButtonProps } from my-ui; const config: ButtonProps { type: primary, size: small };类型定义必须细到props的联合类型枚举不能全部string。用type: primary直接写字符串也能通过类型检查这就是类型带来的开发体验提升。5. 文档书写组件文档即组件演示5.1 文档站选择VitePress适配组件库展示场景文档站我们用了VitePress。为什么不用StorybookStorybook组件探索功能很强但中后台项目更需要的是一篇篇文档、API表格和在线示例。VitePress基于Vite冷启动秒开Markdown写文档天然顺手还支持Vue组件直接嵌入。5.2 文档结构模板化每个组件的文档都按固定模板写这样新开发者在找信息时不需要猜。模板包含组件名称与一句话简介功能特性列表在线演示实时可交互代码示例带源码展示API表格props、emits、slots、expose四张表使用注意与常见问题比如Button文档里的代码示例VitePress里直接写vue代码块支持右上角复制按钮读者一键复制即用。5.3 自动生成props表格手写API表格效率低且容易遗漏字段。我们用了一个小工具读ts类型定义自动生成props表格的markdown片段。这块做成脚本放docs/.vitepress/scripts/gen-props.ts写完组件类型跑一条命令表格自动更新省下大量维护文档的时间。6. 构建产物配置与发布npm6.1 Vite构建配置解析组件库的构建配置直接决定产物质量。核心配置如下import { defineConfig } from vite; import vue from vitejs/plugin-vue; import dts from vite-plugin-dts; import { resolve } from path; export default defineConfig({ plugins: [ vue(), dts({ entryRoot: packages, outDir: [dist/es, dist/lib], tsconfigPath: ./tsconfig.json, }) ], build: { lib: { entry: resolve(__dirname, src/index.ts), name: MyUI, formats: [es, umd], fileName: (format) format es ? index.js : index.umd.cjs }, rollupOptions: { external: [vue], output: { globals: { vue: Vue }, preserveModules: true, preserveModulesRoot: packages, assetFileNames: [name].[ext] } } } });external: [vue]是必需的如果不过滤vue依赖产物里会打包一份Vue运行时和业务方的Vue冲突导致运行时异常。preserveModules开启后产物会保留组件的目录结构dist/es/ ├── button/ │ ├── button.vue.js │ └── style.css ├── input/ │ ├── input.vue.js │ └── style.css └── index.js这样业务方才能精准按需加载。6.2 package.json的exports字段配置package.json里的exports字段定义了不同场景下的入口。我踩过的坑是exports配置错误导致组件库自己的类型在文档站里失效排查了半天发现是exports里类型路径写错了。{ name: my-ui, version: 0.1.0, main: ./dist/lib/index.umd.cjs, module: ./dist/es/index.js, types: ./dist/types/index.d.ts, exports: { .: { types: ./dist/types/index.d.ts, import: ./dist/es/index.js, require: ./dist/lib/index.umd.cjs }, ./es/*: ./dist/es/*, ./dist/*: ./dist/*, ./package.json: ./package.json } }exports里的es/*路径映射是给按需引入用的业务方写import my-ui/es/button/style/index.css时打包器会找到dist/es/button/style/index.css。6.3 npm发布前检查清单发布npm前必须跑一遍检查我整理了一个固定清单执行pnpm build确认构建无报错检查dist/目录产物存在且路径正确用npm pack生成本地tarball检查包内容是否包含dist和类型文件在空白Vue3项目中安装本地包验证全量引入与按需引入确认package.json中files字段包含dist和types目录检查name、version是否与上次发布冲突查看dependencies与peerDependencies是否配置得当6.4 npm发包命令与发布过程发布命令分两步先登录后发布npm login npm publish如果发布私有包用私有registry地址如npm config set registry https://npm.internal.registry/或者在.npmrc文件里配置。发布成功后在业务项目里安装npm install my-ui --save组件库默认只发布最新tag历史版本用npm publish --tag beta发布测试版本时需要指定--tag和--access参数。7. 常见问题与排查技巧实录7.1 “组件未注册”空错误排查这个错误几乎每个用组件库的人都会遇到。全量引入时报Unhandled error during execution of scheduler flush多半是注册时漏了app.use(MyUI)或者全量注册时组件不是标准组件格式没有name。先查注册入口代码确定app.use()有没有执行再确认组件defineOptions里的name是否与组件名一致。7.2 按需引入后样式丢失按需引入样式丢失是最常见的问题排查思路就一条路径检查import my-ui/es/button/style/index.css路径是否正确。如果路径对检查Vite构建的assetFileNames配置是否正确输出了CSS文件以及业务方是否配置了css相关loader。7.3 类型失效与TS报错排除方法类型失效多半是vite-plugin-dts的输出目录和package.json的types字段不一致导致TS找不到类型声明。先确认tsconfig.json里declarationDir再检查types指向的文件是否真实存在。还有一种情况是构建时dts插件输出声明文件被清空插件顺序写错造成调整dts插件放vue()之后即可。7.4 发布后版本号冲突与撤销如果发错版本号或者内容有严重bug用npm unpublish my-ui版本号 --force撤销某个版本。撤销后该版本号不能再重复使用所以发布前一定跑完整测试和构建流程优先保证质量。8. 实操心得与个人经验总结组件库从0到1看起来工作量不大实际涉及的知识面相当宽设计规范、Vue组件机制、Vite构建、类型系统、文档工程、npm发包全流程每一环都有不少隐性细节。我个人最大的收获是组件库不是代码量的积累而是工程化思维的集大成。一开始只想写几个按钮组件做到后面发现难的不是按钮样式而是让每个按钮在任何Vue3项目中都能稳定工作、类型完备、按需打包、样式可定制。这些能力的积累对日常业务开发帮助很大。如果只是做毕设或学习项目我建议先做一个完整的核心组件比如Button把全流程跑通再扩展Input、Select、Table这些常用组件。全流程跑通更重要因为面试官聊的是整体方案而不是组件数量。核心点就一个证明你对这套体系的理解深度而不是广度。最后分享一个细节技巧组件库的代码里尽量少用console.log用debugger代替或者用自定义的logger函数后续排查业务问题时会轻松很多。组件库被业务方引入后组件库里的console.log会直接打到业务的控制台影响别人调试不说有时还会混淆问题来源。这个框架后续还可以扩展接入单元测试覆盖率看板增加自定义主题配置能力或者把常用业务组件如表单弹窗、搜索面板沉淀为高阶组件。从第一个Button到完整组件库这条路值得好好走一遍。
