内部组件库发了个 1.2.0,更新日志写着「Button 支持更多样式」。第二天,三个业务方升级后构建失败,报错说 type 属性不存在。翻代码,组件库把 type 改名成了 variant,旧属性直接删了。按语义化版本,这叫破坏性改动,应该发 2.0.0;但它被当成「新增功能」塞进了次版本。
下游的 package.json 写的是 ^1.0.0,一装就自动升到 1.2.0。没有警告、没有迁移说明,构建直接红。更糟的是,有个业务方用的是锁文件,还没升级,于是线上运行着 1.1.0,本地开发装的是 1.2.0,两个人看到的按钮行为不一样。
这篇讲什么:语义化版本到底承诺了什么、哪些改动算破坏性、变更日志该由谁写、预发布和 dist-tag 怎么用、应用发布和库发布有什么不同、灰度和回滚怎么设计才真的能退。读完你能做到:发版前判断这次该升哪个版本号;把破坏性改动提前告诉下游;给发布加一层按比例放量和快速回退的能力。
版本说明:本文按 Changesets 2.x、npm 11 的发布行为写,灰度和回滚部分用 nginx 与通用概念举例,不绑定具体云厂商。
版本号是契约,不是内部编号
语义化版本(SemVer)的格式是 MAJOR.MINOR.PATCH,含义很具体:
| 位置 | 什么时候加一 | 对使用方意味着什么 |
|---|---|---|
| MAJOR | 有不兼容的 API 变化 | 升级要改代码,必须看迁移说明 |
| MINOR | 向下兼容地新增功能 | 可以直接升,不用改现有代码 |
| PATCH | 向下兼容地修 bug | 可以直接升,行为应该更正确 |
| 预发布后缀 | 1.0.0-beta.1 | 不保证稳定,默认不会被普通范围安装 |
大多数项目在 0.y.z 阶段,规则会宽松一些:主版本为 0 时,任何版本都可能变。但「可以变」不等于「不用告诉别人」。0.x 阶段的库更应该在变更日志里写清楚,因为使用方默认你会乱来。
真正决定使用方会不会自动升级的,是范围符。^1.2.3 允许装到 1.x.x,~1.2.3 只允许 1.2.x。所以一个「次版本里的破坏性改动」,会对所有用 ^ 的项目造成无预警破坏。这不是使用方不小心,是发布方违背了契约。
预发布版本有单独的排序规则:1.0.0-beta.1 小于 1.0.0,默认的 ^1.0.0 不会装到它。要测试预发布版,得显式写 @next 或精确版本,这一点后面讲 dist-tag 时展开。
什么算破坏性改动
很多人把「破坏性」理解成「删了一个导出」。实际范围大得多,尤其对 UI 组件库:
| 改动 | 为什么算破坏性 |
|---|---|
| 删除或重命名导出的组件、函数、类型 | 下游 import 直接失败 |
| 重命名属性,或把可选属性改成必填 | 现有调用方编译失败或运行时报错 |
| 收紧参数校验、改变默认行为 | 签名没变,但结果变了,属于行为破坏 |
| 改变 DOM 结构或公开的 CSS 类名 | 下游的自定义样式、测试选择器会失效 |
| 提高 peer 依赖的最低版本 | 下游的依赖组合可能无法安装 |
| 放弃对某些 Node 或浏览器版本的支持 | 下游的构建或运行环境可能不再可用 |
| 类型定义变严格,原本能过的代码报错 | 对 TypeScript 使用方是编译破坏 |
判断标准很简单:使用方升级后,是否需要改代码、改配置、改样式才能保持原样?需要,就是破坏性。哪怕只影响 5% 的使用方,也是。
有些改动容易漏判。比如「把按钮默认尺寸从 medium 改成 small」,签名完全没变,但所有页面都会变样;「把内部使用的 CSS 类名从 btn 改成 button」,下游覆盖样式的规则全部失效。这类改动必须按 breaking 处理,并在日志里写清楚视觉差异。
如果不想每次都发主版本,可以先走「弃用」流程:保留旧属性,标成 @deprecated,运行时打印一次警告,给下游一个版本的迁移窗口,再在下一个主版本删除。这样破坏性被分摊到两个版本,下游有准备时间。
变更日志:写给人看,不是给机器看
变更日志最常见的失败方式,是自动生成一串提交标题:「fix: typo」「chore: update deps」「feat: refactor button」。版本号升了,使用方仍然不知道要不要升级、升级要改什么。
好的变更日志至少回答三个问题:这次改了什么、对我有什么影响、我要做什么。破坏性改动还要给出迁移前后的代码示例。
谁来写?应该是「改代码的人」,不是发布负责人。发布负责人不可能记得每个 PR 的细节。可行的流程是:每个 PR 必须带一个变更说明文件,合入时由工具汇总成版本号和日志。Changesets 就是这个思路:
# .changeset/quick-lions.md
---
"@acme/ui": major
---
重命名 Button 的 `type` 属性为 `variant`,旧属性已移除。
迁移前:<Button type="primary">
迁移后:<Button variant="primary">
文件里的 major 决定版本号,正文进入变更日志。发布时执行:
pnpm changeset version
pnpm changeset publish
changeset version 会按声明升级版本、生成日志、删除变更文件;changeset publish 负责发布并打 git tag。破坏性改动在 PR 评审时就能被看到,而不是等到发版前才想起来。
另一条路是约定式提交加 semantic-release:根据 feat、fix、BREAKING CHANGE 自动决定版本。它省事,但对提交信息的准确性依赖很高;一个写错前缀的提交,就可能把破坏性改动发成补丁版本。团队如果经常 squash 合并、提交信息不规范,Changesets 这种显式声明更可靠。
日志的组织方式也要固定:破坏性改动放最前,写迁移步骤;然后是新增功能;最后是修复。每条带 PR 或提交链接。不要把所有提交按时间堆上去,使用方关心的是「我受什么影响」,不是「你们这周干了多少活」。
预发布、dist-tag 和发布流水线
npm 的 dist-tag 是「版本别名」。默认发布到 latest,用户 npm install pkg 拿到的就是它。预发布应该发到另一个 tag:
npm publish --tag next
npm dist-tag ls @acme/ui
常见错误是把 1.3.0-beta.1 直接发到 latest。用户没写版本号,一装就装到 beta,出了问题还以为是稳定版。发布脚本里要显式判断:版本号带预发布后缀时,默认 tag 必须是 next 或 beta,不能是 latest。
正式发布时再把版本发到 latest,并可以考虑用 npm dist-tag add 把旧版本的 tag 移走。别手动删版本,npm 上的版本一旦发布就不该撤回;要撤回也得走官方流程,并且已经装过的用户不会受影响。
发布流水线至少包含:安装依赖、构建、测试、生成产物、检查 package.json 的 files 字段、发布、打 tag。可以在 CI 里开启 provenance,让 npm 记录「这个包由哪次构建、哪个仓库产生」,增加供应链可信度。
发布权限要收窄。只有主分支的发布任务能拿到 npm token,PR 任务拿不到;token 用短期或可信发布机制,别在本地长期保存。发布前跑一次 npm pack --dry-run,确认没有把测试文件、源码映射、内部配置打进包里。
应用发布和库发布,不是一回事
组件库面向外部使用方,版本号和日志是契约;业务应用的「使用方」是用户和运维,契约更多体现在「线上是哪一版、能不能回退」。
应用不必严格按 SemVer 递增。更有用的标识是提交 SHA 加构建号,写进 version.json,部署后能核对。版本号可以按产品节奏命名,但每次发布必须能回答:这一版对应哪个提交、包含哪些变更、上一版是哪个。
应用发布也要有变更记录,但读者是客服、运营和运维。写清楚「用户能感知的变化」「需要配置或数据配合的点」「回滚方式」,比列一堆内部重构有用。
库发布和应用发布的共同点是「可追溯」。库追溯到提交和变更说明,应用追溯到提交和产物。没有这层追溯,出了问题只能靠回忆。
灰度:按比例放量,按用户粘住
灰度发布是把新版本先给一小部分用户,观察指标,再逐步扩大。它解决的不是「会不会出错」,而是「出错时影响多少人」。再充分的测试也不能覆盖真实流量,灰度是最后一道缓冲。
灰度要满足三个条件:
- 分流是粘性的。同一个用户每次进来都分到同一组,否则用户会在新旧版本之间来回跳,行为诡异,指标也失真。
- 比例可控。能从 1% 调到 5%、25%、50%、100%,每一步都能停。
- 有护栏指标。错误率、核心转化、接口延迟、白屏率,至少有一组能自动判断「这一版不行」。
nginx 可以用 split_clients 按一个稳定的键分流:
split_clients "${cookie_userid}${remote_addr}" $release {
5% canary;
* stable;
}
location / {
if ($release = canary) {
proxy_pass http://canary_backend;
}
proxy_pass http://stable_backend;
}
更常见的做法是在网关、CDN 或功能开关平台里配置,原理一样:用用户 ID、设备 ID 或会话 ID 做哈希,落到固定桶里。没有稳定标识时,退回 IP 或随机,但要知道这意味着同一用户可能看到不同版本。
灰度的观察期要提前定好,不要「看着还行就全量」。至少覆盖一个完整的业务周期,比如支付类要覆盖一次对账,内容类要覆盖一次发布高峰。样本量太小时,比例再准也看不出问题。
功能开关是另一种「灰度」:代码已经全量部署,但功能只对一部分用户打开。它回退最快,改一个配置就行,不用重新发布。代价是代码里会留下分支,开关长期不清理会变成技术债。每个开关要有负责人和删除时间。
回滚:能退,才敢发
回滚方案要在发布前就确定,而不是出事时现场想。按变更类型分三层:
静态资源回滚看似简单,仍有坑。HTML 被 CDN 缓存,切回旧版本后用户还拿着新 HTML,请求旧资源;或者旧版本目录已经被清理脚本删了,切回去发现文件不在。所以:HTML 不缓存、旧版本保留、回滚脚本要定期演练。
数据库是最难退的部分。一次发布里同时改代码和删字段,代码能回滚,字段删了回不来。稳妥的顺序是「先加后删」:第一次发布加新字段、双写、兼容旧代码;确认稳定后,第二次发布再删旧字段。任何一次发布都不做不可逆的结构变更。
回滚和「向前修复」要分清。小问题、配置类问题,回滚最快;已经产生数据写入、或旧版本不兼容新数据时,回滚可能造成更多问题,这时要评估是修还是退。无论选哪个,都要有明确的决策人和通知渠道。
回滚演练不是形式。每季度挑一个低峰时段,真的把线上切到上一版,跑一遍冒烟,再切回来,记录耗时和卡点。没演练过的回滚方案,大概率在第一次使用时失败。
完整场景走查:一次改名引发的发布事故
回到开头的组件库。修复和改进分两条线走。
第一条线,修正版本策略。把这次改名从 1.2.0 撤回不可能,已经有人装了。做法是立即发 1.3.0,把旧属性 type 加回来,标为弃用,运行时打印警告;同时发 2.0.0-beta,把改名作为主版本变更,附迁移说明和 codemod。下游可以选择先升 1.3.0 消除警告,再安排时间升 2.0.0。
第二条线,补流程。PR 模板里加一项「是否有破坏性改动」,有就要求写 changeset 的 major 说明;CI 检查 changeset 是否存在;发布脚本根据版本号自动决定 dist-tag,预发布绝不发到 latest。这三条落地后,同类问题没有再发生。
业务应用的灰度也在同一周做了一次。新版本先给 5% 用户,观察两小时:错误率没有上升,核心转化持平,接口延迟略降。扩到 25%,再观察四小时;然后 50%、100%,每一步都保留回退开关。第二天发现一个只在灰度组出现的问题:某个旧页面缓存了新 HTML,请求已经清理掉的旧 chunk,报 404。修法是保留最近七个版本的静态资源,HTML 改成不缓存,并在动态导入失败时提示刷新。
回滚演练安排在发布后的第二周。把 current 软链接切回上一版,四十秒完成,冒烟通过,再切回来。演练暴露了一个问题:清理脚本按「保留三个版本」执行,但那次发布连续发了五个补丁版,最早的两个已经被删,回滚到第三个之后就没有更早的了。后来把保留策略改成「保留最近七天,至少五个版本」,并在清理前检查是否有正在回滚的标记。
错误现象对照
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 升级次版本后编译失败 | 破坏性改动被当成新功能,版本号没升主版本 | 看变更日志和实际 diff,确认属性或导出是否被删 |
npm install pkg 装到了 beta | 预发布版本被发到了 latest tag | npm dist-tag ls 看各 tag 指向哪个版本 |
| 灰度用户报错,整体监控正常 | 监控没有按版本维度拆分,或样本太小 | 按版本、渠道、用户分群看错误率和转化 |
| 回滚后仍然报错 | HTML 或 CDN 缓存未清,或数据库做了不可逆变更 | 检查缓存头、旧版本资源是否还在、迁移是否可逆 |
| 变更日志没人看 | 只有提交标题,没有影响和迁移说明 | 看最近三条日志,问使用方能不能照着升级 |
| 两个包版本不匹配 | 多包仓库各自独立发版,依赖范围没同步 | 检查是否该用固定版本或统一版本策略 |
| 发布后旧页面请求资源 404 | 旧哈希文件在部署时被删除 | 查静态资源保留策略和 HTML 缓存策略 |
| 灰度没问题,全量出问题 | 灰度样本偏差,或分流不粘性 | 核对分流键、样本量和观察周期 |
边界与代价
SemVer 不能表达所有变化。「内部重构」「性能优化」「依赖升级」这些改动对使用方的影响很难归类,团队要在日志里补充说明,而不是硬套版本号。把每个小改动都升主版本,会让版本号失去意义;把破坏性改动藏进补丁版本,会让使用方不再信任范围符。
Changesets 对单人项目是额外负担。一个人维护的小库,写变更说明、跑发布命令、管理 tag,可能比直接发版还慢。可以保留「破坏性改动必须写迁移说明」这一条,其余流程简化。流程的价值在于减少沟通成本,不在于文件数量。
灰度需要流量和指标。日活几百的内部系统,5% 只有几十个人,统计上说明不了什么;这时候更有效的是内部试用、按部门放量、或者干脆缩短发布间隔、加快回滚。不要为了「有灰度」而做灰度。
功能开关会积累。每个开关都是一条长期存在的分支,开关越多,测试矩阵越大。给开关设默认值、负责人、清理日期,发布稳定后删掉;删除开关本身也应该是一次有记录的变更。
回滚不是万能的。数据写入、外部回调、缓存状态,都可能让「退回去」比「往前修」更危险。团队要能判断这两种情况,而不是把回滚当成唯一的安全网。
小结
latest;发布脚本自动判断,别靠人记得。当天可以动手的练习:
- 给一个本地包改一个公开属性名,写一条 major 的变更说明,跑一次
changeset version看版本和日志。 - 把预发布版本发到
nexttag,再用npm dist-tag ls确认latest没被污染。 - 给应用加一个
version.json,部署后用 curl 核对提交 SHA。 - 用 nginx 或本地脚本按 5% 比例分流,验证同一个用户每次落到同一组。
- 拿两个版本目录做一次回滚演练,记录耗时,并检查旧资源是否还保留。
这十篇到这里就结束了。从依赖、构建、类型、规范、测试、流水线、配置、样式到发布,串起来是一条完整的「把代码安全送到用户手里」的链路。想继续往下走,可以回到学习路线,按框架与架构方向继续;也可以打开文章列表,挑一个当前项目最疼的点,先把对应的那一篇落地。工程化没有标准答案,只有「这套做法在当前规模下划不划算」。