vue组件库的版本管理与文档构建需深度协同：通过conventional-commits+semantic-release实现自动版本升级与changelog生成，文档站点支持多版本切换、api自动提取、示例嵌入及版本化部署。
Vue 组件库的版本管理与文档构建不是两个孤立环节，而是紧密咬合的生命周期齿轮：版本变动驱动文档更新，文档准确反过来验证版本行为是否符合预期。
语义化版本控制必须落地到每个提交
仅在 package.json 里写 1.2.0 不算真正实践 SemVer。关键在于让每次代码变更自动映射到版本字段：
- 用 conventional-commits 规范提交信息（如
feat(button): add loading state→ 触发 MINOR 升级；refactor(icon): drop legacy props→ 触发 MAJOR 升级） - 集成 semantic-release，它会基于提交解析出应升版本号、生成 CHANGELOG、打 Git Tag、推送 npm，并跳过手动修改 version 字段的出错风险
- 对 Breaking Change 必须同步更新组件的 TypeScript 类型定义和导出结构，否则下游项目升级后会出现类型报错，这比功能不兼容更隐蔽
文档站点要能感知并呈现多版本差异
用户查文档时，最怕看到“最新版”示例却用在旧版项目上跑不通。文档本身需具备版本上下文能力：
- 在 VitePress 或 VuePress 站点头部加入版本下拉菜单，链接指向对应 Git 分支或 tag 构建的静态资源（如
/v1.2.0/components/button） - 每个组件页面底部显示「此页对应 v1.2.0」，并提供「查看 v1.1.0 文档」快捷跳转
- API 表格中对已废弃（deprecated）的 prop 或 event 加灰显+标注废弃版本号（如 size (deprecated since v1.2.0)）
文档内容不能靠手写，而要从源码提取
手写文档注定滞后。真实可行的方式是让文档“活”在组件代码里：
- 在 .vue 文件的
<script setup></script>区块上方添加 JSDoc 注释，描述 props 类型、默认值、是否必填；VitePress 插件可自动解析生成 API 表格 - 把典型使用场景写成
demo/basic.vue、demo/advanced.vue，文档页直接通过<clientonly><demo :src="'./demo/basic.vue'"></demo></clientonly>嵌入可运行示例 - 对样式类名、CSS 变量等非逻辑内容，用
styles/variables.scss中的注释配合提取工具生成主题配置文档
发布即归档，文档部署要绑定版本快照
npm publish 完成后，文档站点不能只更新“latest”，而要确保每个版本都有独立、不可变的访问入口：
- CI 流程中，每次 semantic-release 成功后，触发一次文档构建任务，输出目录按版本号命名（如
dist/v1.2.0） - 部署到 GitHub Pages 或 Vercel 时，启用 versioned subdirectories 模式，而非覆盖
dist/根目录 - 主站首页保留版本切换器，并将
/默认重定向到当前稳定版（如/v1.2.0），避免新用户误入预发布版文档
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
