如何对同一仓库分支管理、版本追踪并部署多版本组件库子站点

一、仓库版本追踪方案 #

• 定死版本规则：严格遵循「主版本.次版本.修订号」的语义化版本规范，比如1.0.0、2.3.1。主版本（第一个数字）只在做不兼容API变更时升级，次版本用于新增功能，修订号仅修复bug。
• Git分支+标签配合：
  • main分支存稳定生产代码，每次主版本发布后打永久标签：git tag v1.0.0，后续回溯旧版本直接拉取对应标签的代码即可。
  • 单独创建release/v1.x、release/v2.x这类分支维护对应主版本，比如v1.x的bug修复全在这个分支操作，不会干扰v2.x的开发进度。
  • 用npm version自动管理版本：比如执行npm version major一键升级主版本，工具会自动更新package.json里的版本号，同时生成对应Git标签，避免手动改版本出错。

二、多版本子站点构建与部署 #

1. 文档与版本绑定构建 #

用Docusaurus、Storybook这类工具就能实现，以Docusaurus为例：

• 执行docusaurus docs:version 1.0，工具会自动复制当前文档到versioned_docs/version-1.0目录，后续v1版本的文档更新直接维护这个目录里的内容即可。
• 构建时，每个主版本会生成独立的静态资源目录，比如build/v1/、build/v2/，对应不同版本的子站点文件。

2. 子站点部署方式 #

• 静态托管服务（Netlify/Vercel/云OSS）：
  配置CI/CD流水线（比如GitHub Actions），每次打主版本标签时自动触发流程：拉取对应标签的代码→构建该版本的文档站点→将build/vx/的内容上传到托管服务的/vx/子路径，用户就能通过your-domain.com/v1/访问v1版本的子站点。
• 自建服务器部署：
  用Nginx做反向代理，将/v1路径指向服务器上/var/www/components/v1目录，/v2指向/var/www/components/v2目录。每次发布新版本，把构建好的静态文件上传到对应目录即可。

三、对齐Angular Material的细节 #

• 在主站点添加版本切换器，让用户能快速切换到不同主版本的子站点。
• 主版本停止维护后标记为「归档」状态，但依然保留子站点访问入口，方便老项目用户查阅旧版文档。

内容的提问来源于stack exchange，提问作者sethbro