vue-vben-admin 中的 Changeset 版本管理与自动化发布实践

vue-vben-admin 中的 Changeset 版本管理与自动化发布实践【免费下载链接】vue-vben-adminA modern vue admin panel built with Vue3, Shadcn UI, Vite, TypeScript, and Monorepo. Its fast!项目地址: https://gitcode.com/GitHub_Trending/vu/vue-vben-admin导读vue-vben-admin 是一个基于 Vue 3、Shadcn UI、Vite 与 TypeScript 构建的 Monorepo 管理后台模板其下同时维护vben/*系列包如vben/common-ui、vben/layouts、vben-core/*系列包以及web-antd、web-naive、web-ele等多个应用。面对如此多包并存的仓库如何为每个包准确记录变更、统一升级版本并生成可读的 Changelog就成了工程化必须解决的问题。项目为此内置了Changeset作为版本管理工具本文将以项目文档 changeset.md 为主线结合实际配置与变更集文件讲清楚 vue-vben-admin 中 Changeset 的完整工作流——从交互式填写变更集、统一提升版本号到自动生成 Changelog 与发布并附上底层实现证据让你能直接在仓库中验证并上手使用。Changeset 是什么为什么 Monorepo 需要它Changeset 是一套面向多包仓库Multi-package Repo或单包仓库的版本管理与发布工具核心价值有三点精确记录变更每次改动以变更集Changeset为单位独立描述谁改了什么、影响哪个包、是patch还是minor一目了然统一计算版本执行发布命令时工具会汇总所有未发布的变更集按语义化版本规则统一提升各包版本号自动生成 Changelog结合 Changelog 生成器如changesets/changelog-github把变更集内容沉淀为每个包或整个仓库的 Changelog 记录。在 vue-vben-admin 这种典型 Monorepo 中多包共享一个 Git 仓库如果没有集中式变更管理很容易出现改了代码却忘记更新版本、多个包版本互不关联导致内部依赖错乱等问题。Changeset 通过pnpm exec changeset这类声明式流程把改代码与发版本解耦让每个 PR 都能附带自己的变更说明。注如果只是个人使用或不需要对外发布版本完全可以跳过 Changeset——项目文档也明确说明如果你不需要它可以直接忽略。项目内的内置命令Changeset 的命令已经直接内置在仓库根目录的 package.json 中通过pnpm run即可调用无需额外安装命令实际执行内容用途pnpm run changesetpnpm exec changeset交互式填写变更集生成.changeset/*.md文件pnpm run versionpnpm exec changeset version pnpm install --no-frozen-lockfile统一提升版本号并更新 lockfile交互式填写变更集当你在分支上完成了一项功能或修复后运行pnpm run changesetCLI 会进入交互式问答引导你完成三件事选择受影响的包从仓库中的包列表里勾选本次改动涉及的那些如vben/common-ui、vben/layouts等选择版本等级为每个包选择patch修复/minor新功能/major破坏性变更填写变更描述用一段简洁文字描述这次改动的内容。完成后工具会在.changeset/目录下生成一个随机命名的 Markdown 文件例如bright-spinners-wait.md内容形如--- vben/layouts: patch --- fix route spinner timing during fast and overlapping navigation这个文件就是一条变更集---块内的 YAML frontmatter 声明了受影响包及其版本等级正文则是给 Changelog 用的变更描述。仓库中已经存在大量这类文件例如.changeset/calm-apes-select.mdvben/common-ui的patch修复.changeset/grouped-form-sections.mdvben-core/form-ui的minor新功能.changeset/kind-cats-breadcrumb.md同时影响vben-core/typings与vben/layouts两个包的minor变更。可以看到一条变更集可以同时声明多个包Changeset 会为每个包独立记录版本等级。命名文件本身是随机的无需也不应手工修改文件名。变更集文件的生命周期填写阶段变更集文件诞生于功能分支随代码一起提交、随 PR 一起评审作为待发布变更的暂存区发布阶段执行version命令后这些文件会被消费版本号被提升、Changelog 被写入随后被自动删除或归档避免重复发布忽略阶段如果某个变更不想纳入版本发布可以通过 .changeset/config.json 中的ignore配置当前为空数组排除对应包。统一提升版本号当你准备好发版时运行pnpm run version这一步实际上执行的是pnpm exec changeset version pnpm install --no-frozen-lockfile它会完成以下工作读取所有未消费的变更集汇总各包的patch/minor/major提升需求更新各包的package.json版本号包括依赖这些包的内部包updateInternalDependencies: patch意味着内部依赖至少跟随patch级更新生成/追加 Changelog把变更集描述写入对应包的 Changelog如 packages/effects/common-ui/CHANGELOG.md重新安装依赖同步更新pnpm-lock.yaml保证 workspace 内部版本引用一致。完成后变更集文件即被消费清除后续的版本发布pnpm publish或通过 CI 自动发布将基于这些已经提升好的版本号进行。配置解析.changeset/config.json仓库根目录下的 .changeset/config.json 是 Changeset 的核心配置它决定了整个版本管理策略{ $schema: https://unpkg.com/changesets/config3.0.0/schema.json, changelog: [ changesets/changelog-github, { repo: vbenjs/vue-vben-admin } ], commit: false, fixed: [[vben-core/*, vben/*]], snapshot: { prereleaseTemplate: {tag}-{datetime} }, privatePackages: { version: true, tag: true }, linked: [], access: public, baseBranch: main, updateInternalDependencies: patch, ignore: [] }各字段含义与项目中的实际取值配置项取值说明changelog[changesets/changelog-github, {repo: vbenjs/vue-vben-admin}]使用 GitHub 关联的 Changelog 生成器生成的记录会关联到对应 GitHub 提交/PR本项目实际仓库地址为vbenjs/vue-vben-admincommitfalse执行version时不在 Git 中自动创建提交由开发者自行提交fixed[[vben-core/*, vben/*]]固定版本组所有vben-core/*与vben/*包被绑定为同一版本号任何一个包发版都会带动整组同步升级保证 monorepo 内部依赖一致snapshot.prereleaseTemplate{tag}-{datetime}快照预发布版本的命名模板用于发布测试性版本privatePackages{version: true, tag: true}私有包也参与版本提升并打 taglinked[]未启用关联版本区别于fixedlinked只保证版本同步提升而不合并为一个版本号accesspublic发布到 npm 时使用 public 访问级别baseBranchmain以main分支作为版本计算的基准分支updateInternalDependenciespatch内部依赖最低以patch级别跟随更新ignore[]当前没有忽略任何包fixed 组vben 家族版本为何始终一致配置中最关键的是fixed项[[vben-core/*, vben/*]]。它把整个vben-core/*与vben/*家族绑定成一个固定版本组。例如vben/layouts发布了5.7.0那么vben/common-ui、vben/core等所有家族包都会同步提升到同一版本。这样做的好处是内部包之间互相依赖时版本号永远对齐避免主版本一致但内部版本错位的隐性问题升级时行为可预期整组一起发版降低排错成本。从仓库根目录 package.json 可以看到项目自身的版本即为5.7.0这与 fixed 组的整体版本节奏一致。快照发布snapshot.prereleaseTemplate支持发布快照版本适用于开发分支上的临时测试。执行类似pnpm exec changeset version --snapshot会根据模板生成{tag}-{datetime}格式的预发布版本号如5.7.0-canary-20260909方便 CI 或协作方提前验证而不影响正式版本线。与 cspell 校验的联动值得注意的一个细节根目录 package.json 中的check:cspell脚本会把.changeset/*.md也纳入拼写检查cspell lint **/*.ts **/README.md .changeset/*.md --no-progress这意味着变更集的描述文本同样需要符合项目的 cspell.json 词表规范避免引入拼写错误。这也是为什么仓库中现存的变更集描述都简洁、规范。发布到 npm配置中的access: public表明这些包以公开方式发布到 npm registry。发布前通常的完整流程为pnpm install pnpm run changeset # 填写变更集开发阶段 pnpm run version # 提升版本号、生成 Changelog pnpm run build # 构建所有产物 pnpm publish # 按各包发布或由 CI 自动化执行构建环节由根目录的build脚本turbo build见 package.json驱动Turborepo 会按照 turbo.json 中的任务依赖关系dependsOn: [^build]先构建依赖再构建被依赖方确保发布出去的包产物完整。发布动作本身也可以交给 CI/CD例如 GitHub Actions 监听版本 tag 触发仓库中的发布配置以 CI 工作流为准人工发布时务必先pnpm run build再pnpm publish。最佳实践小结结合 vue-vben-admin 仓库的实际用法在 Monorepo 中用好 Changeset 有几点经验每笔改动一条变更集功能分支上完成改动后立即运行pnpm run changeset让变更说明跟着 PR 走评审时可读、可追溯准确选择版本等级纯修复用patch新功能用minor破坏性变更用major避免误升版本导致依赖方被动升级善用 fixed 组像项目这样把强耦合的内部包绑定为固定版本组可以显著降低版本维护心智负担发布前先构建pnpm run version之后务必执行pnpm run build确保 npm 产物是全新的无需时可忽略如果项目不对外发布 npm 包Changeset 完全可以不用不影响任何日常开发流程。参考资料项目文档docs/src/en/guide/project/changeset.md另有中文版 docs/src/guide/project/changeset.md脚本定义package.jsonchangeset、package.jsonversion配置文件.changeset/config.json变更集示例.changeset/calm-apes-select.md、.changeset/grouped-form-sections.md、.changeset/kind-cats-breadcrumb.md依赖声明package.jsonchangesets/cli、changesets/changelog-github构建编排turbo.json【免费下载链接】vue-vben-adminA modern vue admin panel built with Vue3, Shadcn UI, Vite, TypeScript, and Monorepo. Its fast!项目地址: https://gitcode.com/GitHub_Trending/vu/vue-vben-admin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考