UI 视觉设计 / 系统课时
按语义版本发布 Token 资源包
按语义版本发布 Token 资源包
把生成好的 CSS 变量、ESM 常量和类型声明发布为可追踪的 npm 版本。本篇以资源包从 1.4.2 升级到 1.5.0 为例,完成兼容性判级、版本和变更记录更新、发布预检,以及组件项目中的锁定、升级与回退。
学习目标
- 根据公开 Token 名称、类型与导出路径选择 PATCH、MINOR 或 MAJOR。
- 更新包版本与
CHANGELOG.md,检查发布内容并完成 npm 发布。 - 在组件项目中锁定指定版本、验证升级,并在出现样式回归时恢复旧版。
按公开契约判定版本级别
将组件能使用的 CSS 自定义属性名、ESM 导出、TypeScript 类型以及 package.json 的 exports 路径视为公开契约。以已发布的 1.4.2 为基线,按兼容性而不是修改文件数判级。
| 实际改动 | 级别 | 下一个版本 |
|---|---|---|
修正 --color-action-primary 的错误回退值,旧引用仍可用 |
PATCH | 1.4.3 |
新增 --color-action-secondary,保留原属性 |
MINOR | 1.5.0 |
删除或改名 --color-action-primary,旧组件样式失效 |
MAJOR | 2.0.0 |
一次发布包含多种改动时,采用破坏性最高的级别。即使变量名不变,品牌颜色改变仍可能令截图或文字对比度发生变化,不能只凭类型检查判断安全;应对 Light、Dark 主题做视觉回归。0.x.y 属于尚未承诺稳定 API 的阶段,正式依赖方宜先明确兼容政策。判断规则参见 SemVer 2.0.0。

配置包入口和变更记录
以下以 npm CLI 10~12 和已有 dist/index.js、dist/index.d.ts、dist/tokens.css 的项目为例。@your-scope/design-tokens 是示例包名,实际发布前必须换成自己拥有权限的 npm scope;发布者须登录相应 registry。
package.json 保留可验证的公开入口,并只把构建产物纳入包:
{
"name": "@your-scope/design-tokens",
"version": "1.4.2",
"type": "module",
"files": ["dist"],
"exports": {
".": {
"types": "./dist/index.d.ts",
"default": "./dist/index.js"
},
"./tokens.css": "./dist/tokens.css"
},
"publishConfig": {
"access": "public"
}
}这是发布清单示例,不会自行生成 dist。在 CHANGELOG.md 为即将发布的 1.5.0 记录日期 2026-10-19、Added:新增 --color-action-secondary、Compatibility:原有变量与导出路径不变、Migration:旧组件无须改代码,新组件按需使用新增变量。若属于 MAJOR,必须具体列出旧名称、新名称和迁移步骤。
预检并发布新版本
先生成并检查 dist,确保类型声明、CSS 与 ESM 来自同一份 Token 源数据;确认本次没有误打包密钥或本地配置。这里选 MINOR,且禁用 npm version 自动创建 Git 提交和标签,便于先审阅变更记录。
npm version minor --no-git-tag-version
npm pack --dry-run预期结果:npm version 输出 v1.5.0,并更新 package.json,存在 package-lock.json 时同步更新其中版本;npm pack --dry-run 的文件清单包含 dist/index.js、dist/index.d.ts、dist/tokens.css。如果缺文件或版本不一致,先修复构建,不要发布。
npm publish --dry-run --access public预期结果:展示拟发布文件与 1.5.0 包信息,不会上传包。审核无误后,将版本文件、变更记录和锁文件提交到 Git,再对对应提交打 v1.5.0 标签;有发布权限、已完成必要身份验证时执行:
npm publish --access public
npm view @your-scope/design-tokens@1.5.0 version预期结果:发布成功后查询返回 1.5.0。若权限或认证失败,发布不会成功,应检查 scope 权限、registry 与登录状态。已发布的同名同版本不能覆盖,修复必须使用新版本号,具体规则可参考 npm publish 文档。
在组件项目锁版并验证升级
在独立组件项目根目录先安装旧版;下面的命令以示例包已在 registry 中发布为前提。
npm install --save-exact @your-scope/design-tokens@1.4.2
npm ls @your-scope/design-tokens预期结果:依赖树显示 1.4.2;package.json 保存精确版本 1.4.2,没有 ^ 或 ~,同时更新 package-lock.json。提交两份文件后,CI 使用 npm ci,会严格按锁文件安装,且不改写锁文件。
npm install --save-exact @your-scope/design-tokens@1.5.0
npm ls @your-scope/design-tokens预期结果:依赖树显示 1.5.0,声明版本和锁文件同时升级。在已有 CSS 导入 @your-scope/design-tokens/tokens.css 的组件项目中,运行项目原有构建与视觉回归检查,至少比较 Light、Dark 各自的 Default、Hover、Disabled,共六组按钮基线。确认新增变量可用且旧引用、类型检查和页面样式不受影响,再合并升级提交。
出现回归时回退消费者
假设升级后 Dark 模式的 Primary 按钮文字对比度由 5.1:1 降为 3.2:1,不满足普通文字 4.5:1 的 WCAG AA 对比度要求。先把受影响组件项目恢复到已验收版本:
npm install --save-exact @your-scope/design-tokens@1.4.2
npm ls @your-scope/design-tokens预期结果:依赖树重新显示 1.4.2;重新运行构建和六组视觉基线后,应恢复旧版样式,并将回退后的 package.json 与 package-lock.json 一起提交。
若 1.5.0 已发布且被确认有缺陷,维护者可在拥有发布权限时标记弃用,而不是删包再用相同版本重发:
npm deprecate @your-scope/design-tokens@1.5.0 "Dark theme regression; use 1.4.2"预期结果:registry 将该版本标记为 deprecated,后续安装它的用户会收到弃用警告;版本内容不会被改写。随后修复对比度并以新版本发布,不能覆盖原来的 1.5.0。