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 发布:
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 写入以下文件内容示例(包名须与实际包名一致):
---
"@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 脚本:
# 先检查待发布变更,再更新版本和日志
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 的发布权限后,才从受控的发布环境执行:
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 版本删除旧接口。