UI 视觉设计 / 系统课时

用语义版本发布组件和令牌包

用语义版本发布组件和令牌包

组件包的 Props 与 Token 包的名称一旦被业务项目依赖,随意修改就可能造成构建失败或样式悄悄变化。本课以同一仓库中的两个 npm 包为例,完成变更分级、版本生成、更新日志、发布验收与项目迁移,让升级者能提前识别不兼容改动。

学习目标

  • 判断 Token 与组件公共接口的变化属于 PATCH、MINOR 还是 MAJOR。
  • 用 Changesets 分别管理两个包的版本和更新日志。
  • 验证构建产物、内部依赖及消费者迁移路径后再发布。

先明确哪些内容需要兼容

假设 npm workspaces 仓库有 packages/tokens 和 packages/react,包名分别为 @example/tokens 与 @example/react(仅作示例,实际操作须换成 package.json 中的真实名称)。本例使用独立版本;若团队选择统一版本,也要同步检查依赖范围。

Token 的公共接口不只有 JSON 键 color.action.primary:已公开的 CSS 变量 --color-action-primary、TypeScript 导出名及跨端资源名称也属于契约。React 包则要保护 Button 的 tone 等 Props、导出类型及文档承诺的交互行为。内部未导出的构建变量通常不算公共接口。

按下游是否需要改代码判定版本

以下示例以已稳定发布的版本为基准,分类规则参见 SemVer 2.0.0。

级别 旧版 → 新版 本项目中的典型变更
PATCH 1.4.2 → 1.4.3 修复 Button 禁用态仍可触发回调的缺陷,恢复已承诺的行为
MINOR 1.4.2 → 1.5.0 新增 color.action.hover;给 Button 增加可选 loading 属性
MAJOR 1.4.2 → 2.0.0 删除或重命名 color.action.primary;把必用的 tone 属性改为 variant

0.y.z 属于 SemVer 的初始开发阶段,不能照搬已稳定版本的兼容保证。计划废弃某个公开 API 时,先以 MINOR 发布弃用提示和替代方案,真正移除时再升 MAJOR。

语义版本判定、双包发布与项目升级的流程

用 Changesets 写出可审查的变更记录

在仓库根目录安装工具并初始化;前提是两个包已在根 package.json 的 workspaces 中声明,且允许发布。以下命令只初始化工具,不会向 npm 发布:

bash
npm install --save-dev @changesets/cli
npx changeset init

预期结果:仓库新增 .changeset/config.json。之后每个影响公开接口的合并请求附带一份 Changeset,而不是等发布前凭记忆补日志。

假设 Token 当前为 1.4.2,React 当前为 2.3.1;本次既更名公开 Token,又把公开的 Button tone 改为 variant,两包均有破坏性修改。在 .changeset/rename-public-api.md 写入以下文件内容示例(包名须与实际包名一致):

markdown
---
"@example/tokens": major
"@example/react": major
---

BREAKING: Rename `color.action.primary` to `color.interactive.primary`.
BREAKING: Replace the Button `tone` prop with `variant`.
Migration: Update token references and change `tone="primary"` to `variant="primary"`.

这份记录会参与版本计算并写入各包的 CHANGELOG.md。如果只改了 React 内部对 Token 的调用,而 React 的公共接口完全不变,就不能机械地把它也判为 MAJOR;还须检查内部依赖升级是否改变消费者的实际行为。

升版、验包,再执行发布

合并变更后,在无其他待发布 Changeset 的前提下,按顺序执行;示例假定仓库根目录已有有效的 build、test 脚本:

bash
# 先检查待发布变更,再更新版本和日志
npx changeset status
npx changeset version
npm run build
npm test
# 只检查包内文件,不实际上传
npm pack --dry-run --workspace packages/tokens
npm pack --dry-run --workspace packages/react

预期结果:status 能识别两个 MAJOR 变更;version 将示例包分别升至 2.0.0 与 3.0.0,更新相应日志;测试通过,npm pack --dry-run 列出将发布的文件但不上传。重点查看 CSS、类型声明和组件构建文件是否都在包内,并确认 React 对 Token 的依赖范围已适配新版本,例如由 ^1.4.2 调整为 ^2.0.0。

只有完成代码审查、CI 校验、更新日志和产物检查,并配置好目标 npm registry 的发布权限后,才从受控的发布环境执行:

bash
npx changeset publish

预期结果:Changesets 尝试发布尚未发布的包版本并创建对应 Git 标签;具体成功信息取决于 registry 和权限。包名与版本一经发布不能覆盖同名同版本产物,因此失败时先排查权限、构建与版本状态,不要试图修改已发布的内容。操作细节参见 Changesets 发布指南。

给使用方一份能照做的迁移单

在 MAJOR 版本说明中同时写明旧用法、新用法、受影响范围和验收方法。本例要求业务项目把 color.action.primary 引用改为 color.interactive.primary,把 <Button tone="primary" /> 改为 <Button variant="primary" />;升级到 Token 2.0.0 与 React 3.0.0 后重新构建、运行组件交互测试,并对 Light/Dark 两个主题做视觉回归。

原来依赖范围为 ^1.4.2 的项目不会仅靠正常兼容更新自动获得 2.0.0;必须显式调整依赖版本及锁文件。若多个项目暂时无法同步迁移,可在前一个 MINOR 版本先保留旧别名并发出弃用提示,让消费者分批改造,最后在 MAJOR 版本删除旧接口。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用语义版本发布组件和令牌包

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通