Angular 框架版本演进全记录：深入解读 CHANGELOG_ARCHIVE.md 的发布历史档案机制

本文基于 Angular 开源仓库中的 CHANGELOG_ARCHIVE.md，系统解读这份约 9600 行的发布历史档案：它如何与主 CHANGELOG.md 配合完成版本日志的分段归档、每条发布记录的结构规范（版本锚点、提交表格、Special Thanks 致谢区），以及 2.0、13.0 等里程碑版本中 breaking changes 的书写范式，帮助你在排查 API 行为变化、追溯历史 bug 修复时快速定位可靠依据。

一、档案定位：主日志与历史归档的双文件结构

Angular 仓库根目录维护着两份发布日志文件，构成“现行日志 + 历史归档”的双文件结构：

• CHANGELOG.md：记录最近版本的发布内容。以当前仓库快照为例，其首条记录为 22.2.0-next.4 (2026-08-26)，并向下延续最近的稳定版与小版本修复记录（如 22.1.4、21.2.22、20.3.30 等同日维护的修复）；
• CHANGELOG_ARCHIVE.md：本次解读的核心档案，收录 13.3.11 (2022-05-31) 一路回溯至 2.0.0 (2016-09-14) 的全部发布记录，跨越 Angular 2 代至 13 代近十年的版本演进。

从两份文件的共同格式特征可以确认其分段机制：每条版本记录之间都有一行 HTML 注释标记 <!-- CHANGELOG SPLIT MARKER -->。例如 CHANGELOG.md 的第 45 行与 CHANGELOG_ARCHIVE.md 的第 9 行都出现了这一注释。可以推断，仓库的发布工具链正是以该标记为切分点，在发布新周期时将滚动超出保留窗口（v13.3.11 及之前）的条目整体迁移进归档文件，从而让主日志始终保持轻量、只聚焦于近期版本——这正是两份文件头部版本号首尾相接（主日志承接 14.x 及以后，归档文件止于 13.3.11）的原因。

这种结构的实用价值在于：当你排查一个较老版本的行为差异时，无需翻找 git 标签，直接在本档案中检索版本号即可获得该版本的完整变更清单与提交溯源信息。

二、单条发布记录的结构规范

以归档档案中的 13.3.7 (2022-05-11) 条目为例（见 CHANGELOG_ARCHIVE.md），一条标准发布记录由四部分构成：

1. 版本锚点：<a name="13.3.7"></a>，为每个版本号提供可直链的 HTML 锚点，便于从外部文档、issue 讨论中直接引用某次发布；
2. 版本标题：# 13.3.7 (2022-05-11)，版本名与发布日期并列，日期即该标签的发布日；
3. 按包分组的提交表格：每个受影响的包（如 core、language-service）下有一张三列表格，列为 Commit | Type | Description。例如该版本中：
   • core 包收录了一条 perf 类型提交：allow checkNoChanges mode to be tree-shaken in production；
   • language-service 包收录了一条 fix 类型提交：Add resource files as roots to their associated projects。
4. Special Thanks 致谢区：列出该发布周期内贡献了被合并提交的社区成员。例如 13.3.10 (2022-05-25) 条目中列有 A. J. Javier、Joey Perrott、dario-piotrowicz 等 13 位贡献者（见 CHANGELOG_ARCHIVE.md）。

其中 Type 列沿用了 Conventional Commits 的类型词表：feat（新功能）、fix（缺陷修复）、perf（性能改进）。表格中每个 Commit 单元格都带有指向提交页的链接，这使得任何一条变更都可以下钻到具体的代码差异，形成“日志条目 → 提交 → PR”的完整证据链。

值得注意的是，部分维护性版本（如 13.3.11、13.3.6）只有致谢区而无提交表格，说明这些版本可能主要是依赖升级或内部维护变更，日志保留了版本节点本身以保证版本序列的连续性。

三、里程碑版本 v13.0.0：破坏性变更的完整书写范式

归档档案中信息密度最高的条目是 # 13.0.0 (2021-11-03)（见 CHANGELOG_ARCHIVE.md）。它示范了 Angular 主版本升级时 breaking changes 的记录规范：按受影响的包（common、core、forms、router、service-worker 等）分节，逐条说明行为变化、影响面与迁移方式，而非仅仅罗列符号删除。以下节选其要点：

core：运行环境与符号移除

• TypeScript 版本低于 4.4.2 不再受支持；
• Node.js 版本低于 v12.20.0 不再受支持，原因是 Angular 各包开始使用 Node 的 package exports 子路径特性；
• WrappedValue 类不再从 @angular/core 导出，仍在使用它的旧第三方库会在编译期或运行期失败，且官方不提供替代方案，只能移除相关用法。

forms：状态类型的收窄

引入联合类型 FormControlStatus，将 AbstractControl.status 从 string 收窄为 FormControlStatus，statusChanges 相应从 Observable<any> 收窄为 Observable<FormControlStatus>。档案明确提示了两种典型破坏场景：应用将 status 与非法状态字符串比较，或将 statusChanges 事件当作非字符串消费——这为使用者自查迁移提供了判据。

router：URL 解析与导航语义修正

• 默认 URL 序列化器不再丢弃问号之后的内容：导航到 /path?q=hello?&other=123 时，查询参数将正确解析为包含 ? 的值，而非截断；
• routerLink 的 null/undefined 输入不再等价于空字符串，且 href 由属性绑定改为 HostBinding('attr.href')，影响依赖 DebugElement.properties['href'] 的测试断言；
• 新的导航取消旧的进行中导航时，Router 不再替换浏览器 URL（此前该行为会造成 URL 闪烁，仅服务于部分 AngularJS 混合应用），混合应用需自行订阅 NavigationCancel 事件并调用 location.replaceState；
• Route.loadChildren 不再支持字符串形式，NgModuleFactoryLoader、SystemJsNgModuleFactoryLoader 从 @angular/core 移除，SpyNgModuleFactoryLoader、DeprecatedLoadChildren 不再由 @angular/router 导出，setupTestingRouter 签名随之简化。

service-worker：返回类型变化

SwUpdate#activateUpdate 与 SwUpdate#checkForUpdate 的返回类型变为 Promise<boolean>，在少数场景下会导致 TypeScript 类型检查失败，需要按新返回类型更新声明。

Deprecations：弃用而非删除

13.0.0 的弃用清单体现了 Ivy 编译器落地后对 ViewEngine 时代 API 的系统性清理：ViewContainerRef.createComponent 的工厂签名、getModuleFactory（改推荐 getNgModuleById）、PlatformRef.bootstrapModuleFactory 与 ApplicationRef.bootstrap 的工厂签名均被弃用；Compiler、CompilerFactory、JitCompilerFactory、NgModuleFactory 等 ViewEngine JIT 专用符号整体弃用（档案特别注明这不影响 Ivy 下的 JIT 模式）；@angular/platform-server 中 renderModuleFactory 被 renderModule 取代。每条弃用说明都给出了对应的替代 API，是典型的“平滑迁移”式弃用记录。

四、早期 2.x 系列：Conventional Changelog 的 bullet 格式

档案末尾（CHANGELOG_ARCHIVE.md）保留了 2.0.0 至 2.2.0-beta.1 时期的记录，其格式与 13.x 的表格体例明显不同，采用的是经典 Conventional Changelog 输出样式，按类型分节：### Features、### Bug Fixes、### Performance Improvements、### Code Refactoring，并在存在破坏性变更时附加 ### BREAKING CHANGES 专节。

每条 bullet 遵循 scope: 描述 (commit 短哈希), closes #issue 的模式，scope 即当时仓库的包名，例如：

• 2.1.0 (2016-10-12) 的 Bug Fixes 节收录了 compiler、forms、http、router、upgrade 等 scope 的修复，如 router: wildcards routes should support lazy loading、forms: properly validate blank strings with minlength；
• 2.2.0-beta.0 (2016-10-20) 的 Features 节记录了 router: add support for ng1/ng2 migration、forms: add hasError and getError to AbstractControlDirective 等特性；
• 2.2.0-beta.1 的 BREAKING CHANGES (only for beta version users) 专节则说明 downgradeComponent、UpgradeComponent 等四个新 API 改从 @angular/upgrade/static 导入。

这类条目还附有版本包含关系的注释，如 “The 2.2.0-beta.1 release also contains all the changes present in the 2.1.2 release”，明确了预发布版本与稳定版修复的叠加关系。对比 2.x 的 bullet 体例与 13.x 的表格体例，可以观察到该仓库日志格式随时间演化：从纯文本 bullet 迁移到按包分组、带 Commit/Type/Description 三列的结构化表格，检索性与机器可解析性都在增强。

五、发布日志与提交、标签的生成关系

从档案中每条变更都携带提交哈希与 PR 编号来看，日志是以 commit 历史为唯一数据源生成的。仓库内 tools/gulp-tasks/changelog-zonejs.js 提供了同一套工具链的一个可参照实现：该 gulp 任务使用 gulp-conventional-changelog 并以 preset: 'angular' 生成 packages/zone.js/CHANGELOG.md，其关键配置有三点值得注意：

• 版本号从 git 标签解析（zone.js- 前缀剥离后得到真实版本）；
• 通过 previousTag/currentTag 界定两个标签之间的提交区间；
• 用正则 ^((feat|fix|perf)\(zone\.js\)|revert:.*\(zone\.js\)) 过滤出 scope 为 zone.js 的提交，忽略其他包的提交。

据此可以推断，主框架的 CHANGELOG/ARCHIVE 同样遵循“Conventional Commits 规范 + 按包 scope 过滤 + 标签区间”的生成路径：提交消息中 feat(core): ... 的 scope 决定了它最终落在日志哪个包的小节下，Type 列即提交类型前缀。这也解释了为什么 13.3.8 条目中 language-service 小节下会出现 “Prevent TSServer from removing templates from project” 这类精确到单一修复的记录——它就是对应 PR 合并提交经过滤后的原样呈现。

六、实战检索指南

基于上述结构，对 CHANGELOG_ARCHIVE.md 的高效检索可以按三条路径进行：

1. 按版本号定位行为差异：直接检索 # 13.0.0 (、# 2.1.0 等标题行，进入该条目逐包浏览 Breaking Changes 与提交表格。排查“某 API 何时失效”类问题时，优先检查对应主版本的 Breaking Changes 节；
2. 按 API 名反查影响版本：例如检索 WrappedValue、renderModuleFactory、FormControlStatus，可立即得到引入变化或弃用的版本条目及其上下文说明；检索 checkNoChanges 则可看到 13.3.7 中关于生产环境 tree-shaking 的性能改进；
3. 按提交哈希下钻：表格与 bullet 中的 Commit 链接均指向具体提交，结合 PR 链接可进一步查看变更讨论与测试范围，形成从日志到代码的完整溯源链。

需要说明的适用边界：本档案覆盖的版本区间为 2.0.0（2016-09-14）至 13.3.11（2022-05-31），v14 及以后的发布记录请查阅主日志 CHANGELOG.md；档案中的提交与 PR 链接指向社区上游代码托管地址，仅作为溯源标识。对于依赖这些历史版本的代码库，升级前通读目标版本条目的 Breaking Changes 与 Deprecations 小节，是迁移成本最低、风险最可控的做法。