企业官网建设流程全解析

Carbon Design System 发布事故复盘：@carbon/icons-angular v10.5.0 损坏构建事件

【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon

本文以 IBM Carbon Design System 仓库 docs/postmortems/2019-08-15-icons-angular.md 的正式事故复盘（postmortem）记录为骨架，完整还原@carbon/icons-angularv10.5.0 发布损坏构建的全过程：从依赖范围（caret range）如何放大影响、根因（构建步骤被注释掉却未设置private字段）如何形成、到利用 npm 的 72 小时unpublish窗口快速止血。读者可以从中掌握一套可复用的"多包发布事故处置方法论"，并理解 semver、peerDependencies、npm dist-tag 与代码审查防护在真实开源项目中如何协同生效。

一、事件背景：postmortem 文化与本文档的定位

在深入事故细节之前，先理解这份文档在仓库中的位置。Carbon Design System 在 docs/postmortems/README.md 中明确了对事故复盘的定义：

A postmortem is a written record of an incident, its impact, the actions taken to mitigate or resolve it, the root cause(s), and the follow-up actions to prevent the incident from recurring.

即事故复盘是一份书面记录，涵盖：事件经过、影响范围、为缓解或解决事件所采取的行动、根因，以及防止事件再次发生的后续动作。仓库为此提供了标准模板 docs/postmortems/0000-00-00-template.md，模板要求按固定结构填写：

• Summary：一两行事件摘要；
• Impact：事件影响范围；
• Root causes：事件发生的主要原因；
• Detection：如何发现事件；
• Resolution：如何缓解影响；
• Action Items：后续动作及负责人、关联 Bug/PR；
• Lessons learned：做得好的、做错的、幸运之处；
• Timeline：关键时间线。

文件名遵循YYYY-MM-DD-title.md的约定，例如本次事件的2019-08-15-icons-angular.md。本仓库中还有多份同类复盘，如 2019-09-26-v10.6.4-patch-release.md（patch 发布混入新功能）、2019-10-07-content-switcher-breaking-change.md（语义化版本破坏性变更）、2020-04-09-v10.11.0-release.md（Sass@error表达式位置错误导致构建失败）。它们共同构成了 Carbon 团队对"发布事故"的系统性复盘文化——这也是本文能够详细拆解本次事件的基础。

二、事件概述：v10.5.0 发布了一个损坏的构建

Summary（原文）：

The v10.5.0 release of the Carbon Design System shipped a broken build of@carbon/icons-angular.

2019 年 8 月 15 日，Carbon Design System 的 v10.5.0 版本对外发布了，但其中@carbon/icons-angular（Carbon 图标的 Angular 封装包）的构建产物是损坏的。也就是说，用户通过 npm 拉取到的这个版本，其lib目录下的构建产物无法正常工作，属于典型的"发布即事故"。

三、影响面分析：caret range 与 peerDependency 的组合放大效应

事故的影响面不是个别的，而是系统性的，原文Impact部分给出了两个关键机制：

1. caret range（^）依赖范围：受影响的团队集中在那些使用^来跟踪@carbon/icons-angular依赖的10.x范围的用户。按照 semver 语义，^10.x.x允许在10.x主版本内自动接受minor/patch更新。因此，当v10.5.0发布后，任何"新装依赖"（fresh install）或 CI 中执行自动依赖解析的团队，都会在不知情的情况下被解析到损坏的v10.5.0。

2. peerDependency 范围：carbon-components-angular在它的peerDependencies中把@carbon/icons-angular指定为^10.1.0。这意味着凡是安装carbon-components-angular的项目，都会随之解析到^10.1.0允许范围内的最新版本——即刚发布的损坏版本v10.5.0。peerDependency 的存在让损坏版本在依赖树上被"自动传染"给更多下游团队。

这两点共同说明：在一个由多包组成的开源设计系统中，一个子包的损坏发布，会通过依赖解析器的自动升级机制迅速扩散到整个消费生态。这与 docs/guides/versioning.md 中"每次 minor/patch 更新都应该让使用者放心升级而不会破坏项目"的承诺形成鲜明对比——本事件正是对这一承诺的意外破坏，因此团队后续将 semver 合规性提升为发布流程中的重点检查项。

四、根因分析：三重防线同时失守

原文Root causes部分揭示了事故的完整链条，可以拆解为三个层面：

4.1 上游变更：图标缩到 16px 引入构建问题

Carbon Design System 核心团队当时引入了一个"将图标尺寸缩小到 16px"的选项（对应 PR #3501）。这一变更在@carbon/icons-angular的构建流程中引发了构建相关问题（build-related issue）。

4.2 临时处置：注释掉构建步骤

面对构建问题，当时的建议处置方式是注释掉构建步骤（comment out the build step），以便团队能够继续推进后续工作。这是一个典型的"临时绕过"操作——它让代码库处于"能提交、不能正确构建"的中间状态。

4.3 遗漏防线：未设置private字段 + 审查流程缺位

关键在于，临时绕过时没有同时在该包的package.json中设置private: true字段。npm 的private: true声明会阻止包被意外发布到 registry——这是防止"带病发布"的标准保险丝。由于这个保险丝缺失，处于损坏状态的包在后续发布流程中被真实地推送到了 npm。

此外，GitHub 界面上没有触发对@carbon/icons-angular的CODEOWNERS（代码所有者）的最终审查提示。也就是说，发布前缺少了一个"懂这个包的人"的最终确认环节。

一句话总结根因：上游变更引入了构建问题 → 临时注释构建步骤绕过后没有做发布防护（缺private字段）→ 审查流程没有兜底拦截 → 损坏版本被发布。

五、检测与响应：从 Slack 报告到确认只用了约 3 小时

原文Detection部分记录，该问题首先由 @cal-smith 报告。而Timeline部分给出了当天（2019 年 8 月 15 日，全部为 UTC 时间）的完整处置时间线：

从首次报告（17:50）到完成 unpublish 止血（20:07），全程约2 小时 17 分钟。需要说明的是，原文档时间线标题写作 "2015-08-15"，结合文档 frontmatter 的date: 2019-08-15可以判断这是原文档中的笔误，实际事件发生在 2019 年。

这条时间线本身就是一个值得学习的模板：外部社区成员第一时间报告 → 团队快速确认并给出 ETA → 确认影响后立即执行回滚。快速响应能力直接决定了一次发布事故的损失边界。

六、解决方案：利用 npm 的 72 小时 unpublish 窗口回滚

原文Resolution部分给出了这次止血的具体操作，这是本文最具操作价值的部分：

Sincev10.5.0was recently released, we decided to use theunpublishfeature ofnpmthat is valid within 72 hours of a release. Running this command subsequently unpublished the broken build of@carbon/icons-angularand restoredv10.4.0as thelatestpackage for teams to consume.

关键要点拆解：

1. npm unpublish是唯一能在发布后快速"撤回"版本的机制，但 npm 只允许在发布后 72 小时内对包执行 unpublish。一旦超过这个窗口，版本将永久保留在 registry 上，只能通过发布新版本覆盖或手动调整 dist-tag 来缓解。
2. 执行 unpublish 后，v10.4.0自动恢复为latest。这是因为latestdist-tag 始终指向最高已发布版本；当损坏的v10.5.0被移除后，依赖解析会自动回落到此前的最高版本v10.4.0，使用^10.1.0等范围的项目会解析到健康的v10.4.0。
3. 这次能成功止血，得益于事件发生在发布后极短的时间内——这正是复盘文档 "Where we got lucky" 中强调的幸运因素：仍在 npm 的 72 小时 unpublish 时限内。

这一机制与仓库 docs/release.md 中描述的发布治理一脉相承。该文档展示了更完整的发布链路：prerelease（nexttag）→ stable release（提升到latesttag）→ post release 监控，以及在问题无法快速修复时"回滚到上一个稳定版本"的策略（npm dist-tag add package@version latest）。本次事件本质上就是"回滚到上一个稳定版本"策略在 72 小时窗口内的一次成功执行。

七、Action Items：用private: true堵住制度漏洞

复盘最重要的产出是防复发措施。原文Action Items表格记录了唯一一项后续动作：

即：为@carbon/icons-angular的package.json设置private字段，从机制上杜绝"构建处于损坏状态却仍然被发布"的可能性。这是一项"一次性修复、永久生效"的制度性补丁——不依赖任何人的责任心，而是让 npm 本身拒绝发布。

这一点在当前仓库的包结构中得到了印证。以同族的图标包为例：

• packages/icons/package.json（@carbon/icons）：

  { "name": "@carbon/icons", "version": "11.88.0", "publishConfig": { "access": "public", "provenance": true }, "scripts": { "build": "yarn clean && node tasks/build.js", "clean": "rimraf es lib metadata.json svg", "prepublishOnly": "yarn build" } }

  值得注意prepublishOnly: yarn build——发布前强制构建，若构建失败则发布中止，这正是对"注释掉构建步骤导致带病发布"一类事故的直接制度化防御。

• packages/icons-react/package.json（@carbon/icons-react）：声明了peerDependencies: { "react": ">=16" }，并且build脚本为yarn clean && node tasks/build.js。
• packages/icons-vue/package.json（@carbon/icons-vue）：同样具备publishConfig.access: public与明确的构建脚本。

此外，仓库中不对外发布的可执行包会显式标记"private": true，例如 packages/carbon-components/package.json 与 packages/carbon-components-react/package.json。可以看到，"该发布的包公开、不该发布的包标记 private"这一纪律已经成为当前仓库的标准实践。而从当前仓库目录结构看，packages/下已不再包含icons-angular包（仅有icons、icons-react、icons-vue等），Angular 图标包的维护已迁移到独立仓库，但这次事故沉淀下的发布防护原则仍然适用。

八、Lessons Learned：一次事故的三面镜子

原文在 "What went well"、"What went wrong"、"Where we got lucky" 三个维度做了自我剖析，这也是 postmortem 文化中最有价值的部分：

做得好的（What went well）

• 事件上报后的解决速度非常快（"The time it took to resolve the issue was fast after it was first reported"）。从第一次报告到 unpublish 完成仅约 2 小时 17 分钟，快速响应避免了影响面进一步扩大。

做错的（What went wrong）

• 在移除底层构建函数的同时，没有把包设置为private来防止意外发布（"We contributed code that took away the underlying build functions without setting the package toprivateto prevent accidental publishing"）。这是整起事故最核心的失误：改动构建逻辑本身并不可怕，可怕的是改动后没有同步加上发布保险，让一个"没有构建能力"的包进入了发布管道。

幸运之处（Where we got lucky）

• 仍然处于 npm 的 72 小时 unpublish 时限内（"We were still within the 72 hour time period required bynpmfor theirunpublishfeature to work"）。如果发现时间再晚几天，损坏的v10.5.0将永久停留在 registry 上，处置成本会从"unpublish"升级为"发布修复版 + 引导用户升级"，且使用旧范围的团队将持续踩坑。

九、给多包发布团队的工程启示

综合本次复盘，可以提炼出几条可迁移到任何多包发布场景的工程实践：

1. 临时绕过必须配套临时保险：任何"注释掉构建步骤"式的临时处置，都必须同步考虑它是否会让系统进入"可发布但不可用"的状态。此时设置package.json的private: true或移除发布脚本（如prepublishOnly）是最低成本的防护。
2. 发布前强制构建：参考当前仓库图标包的做法，在prepublishOnly中执行yarn build，让"构建失败 → 发布失败"成为硬约束，而不是依赖人工检查。
3. 依赖范围要意识到自动升级风险：^范围和 peerDependency 会在新版本发布瞬间自动扩散影响。设计系统这类被广泛依赖的多包项目，发布前对"谁在用这个包、用什么范围在用"要有明确认知。
4. 用 npm dist-tag 机制管理回滚：72 小时内的unpublish可恢复latest；超过窗口后，则应像 docs/release.md 所述，通过npm dist-tag add package@version latest手动把latest指回健康版本，并主动通知下游。
5. postmortem 制度化：按 docs/postmortems/0000-00-00-template.md 的模板，在事故后 72 小时内完成复盘记录，明确 Action Item 与 Owner，并像本次一样将修复落在代码机制上而非口头承诺。

十、结论

@carbon/icons-angularv10.5.0 损坏构建事件，是开源设计系统多包发布历史上一个教科书级的"小疏漏、大影响、快止血"案例：一个未设置private字段的遗漏，经由^范围与 peerDependency 的自动解析机制，扩散到整个carbon-components-angular消费生态；而一次在 72 小时窗口内果断执行的npm unpublish，又迅速将生态恢复到了健康的v10.4.0。它最终沉淀为一条制度性修复（PR #3744 设置private字段），并成为本仓库 postmortem 文档集中最值得反复阅读的一页。

【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon