企业官网建设流程全解析

• 开发工具
• CLI
• 文档

本文以 standard-changelog 的 CHANGELOG 为核心，完整梳理这个包从 2016 年 1 月初始化（0.0.1）到 2026 年 7 月（8.1.0）的全部版本变更、各次破坏性变更的迁移影响，并结合当前仓库源码给出 8.x 版本的完整 CLI 参数与 JS API 用法。读完本文，你可以准确判断从旧版本升级需要处理哪些断点，并掌握在 Node.js 22 环境下用 Angular 提交约定生成 CHANGELOG 的两种方式。

什么是 standard-changelog

standard-changelog的定位可以用一句话说清：它是conventional-changelog生成器内置了 Angular 提交约定预设的版本，读取 git 历史后生成CHANGELOG.md，把提交自动归组为 Features、Bug Fixes、Performance Improvements 等小节。与通用conventional-changelog的唯一区别是无需安装或选择预设——它永远使用 Angular 预设（见 README 与 文档站入口页）。

从当前仓库的 package.json 可以确认 8.1.0 的关键事实：

• type: module，ESM-only 包；
• engines.node: ">=22"，即要求 Node.js 22 或更高；
• 运行时依赖仅三个工作区包：@conventional-changelog/git-client、conventional-changelog-angular（预设）、conventional-changelog（核心生成器）；
• 发布时挂载standard-changelog命令（publishConfig.bin）。

十年版本时间线（2016–2026）

以下各节内容均直接来自 CHANGELOG.md，按年代分段归纳。

2016–2018：初始化与 2.0 里程碑

• 0.0.1（2016-01-30）：初始版本，CHANGELOG 记录其初始化关闭了上游 conventional-changelog 仓库的 issue #84——这个包从诞生起就是 conventional-changelog 工具链的一部分。
• 1.0.0 → 1.0.19（2017-03-11 至 2018-04-16）：1.x 系列共 19 个版本，CHANGELOG 中均为 "Version bump only" 条目，无独立功能记录，属于跟随 monorepo 联动的维护期。
• 2.0.0（2018-05-29）：唯一的 2.x 早期重大变更是把包最低 Node 版本要求定为"当时 Node 发布工作组支持的最老 LTS"（即 Node 6，处于 Maintenance LTS 阶段），构成一次破坏性变更。
• 2.0.2（2018-11-01）：升级 Lerna 3，修复 Node.js v11 下的错误（issue #385）。

2018–2020：2.0.x 长期维护期

2.0.3 到 2.0.27（2018-11-01 至 2020-11-05）是典型的 monorepo 联动维护期，大量条目只有 "Note:Version bump only for package standard-changelog"，但其中几个安全/依赖类修复值得关注：

可以看到这条维护期的主线是依赖安全加固与CLI 类型补全，包本身行为稳定。

2023：三次重大架构版本（3.0.0 / 4.0.0 / 5.0.0）

2023 年 5 月到 9 月间连续发布了 3.0.0、4.0.0、5.0.0 三个破坏性版本，是这个包历史上变化最密集的时期：

• 3.0.0（2023-06-06）：要求 Node >= 14；CLI 工具开始支持Lerna 风格的pkg@version标签（#175）；补充 CLI flags 类型（#551）；重构中尽可能移除 lodash 依赖（#959）。
• 4.0.0（2023-08-26）：要求 Node >= 16；所有预设统一改为导出"预设配置工厂函数"，conventional-changelog-preset-loader新增loadPreset与createPresetLoader两个导出。CHANGELOG 特别说明：如果你的项目只是按名字间接引用预设，则无需改配置，升级包即可。另外从 chalk 迁移到 picocolors（#1074），并修复了 semver 漏洞（#1071，关闭 #1019）。
• 5.0.0（2023-09-08）：回调全面 Promise 化。与 standard-changelog 直接相关的是其createIfMissing方法从此返回 Promise；同批次的git-semver-tags、conventional-recommended-bump包（gitSemverTags、conventionalRecommendedBump函数）也改为返回 Promise（#1111、#1112）。

2024–2026：ESM-only、Builder API 与手动提交范围

• 6.0.0（2024-04-26）：要求 Node >= 18；除gulp-conventional-changelog外所有包转为 ESM-only（CJS → ESM 迁移，#1144）；修复了 config 加载问题（#1234）；meow 升级到 v13（#1190）。
• 7.0.0（2025-05-19）：核心架构合并——conventional-changelog-core与conventional-changelog-cli两个包并入conventional-changelog，同时引入全新 Builder API 与更新后的 CLI flags（#1352）。7.0.1 是同日的构建修复。当前 src/index.ts 中StandardChangelog extends ConventionalChangelog的继承关系就是这一合并的产物。
• 8.0.0（2026-06-26）：要求Node.js 22 或更高；新增手动提交范围支持（#1486），即 CLI 的--from/--to参数。
• 8.0.1（2026-07-04）：把包的 homepage 与文档指向迁移到文档网站。
• 8.1.0（2026-07-09）：CLI 参数解析从meow替换为argue-cli（#1505）。当前 cli.ts 中的readFlags()/runProgram()即替换后的驱动方式。

破坏性变更与升级要点

把上表按版本压缩成升级决策清单：

需要说明的适用前提：7.0.0 起 CLI flags 的变化意味着 6.x 时代脚本里使用的旧参数名在 7.x/8.x 下不再有效，迁移时应以standard-changelog --help输出和当前 cli.ts 中的参数清单为准。

当前版本（8.x）的 CLI 用法

README 给出的最小用法是：

standard-changelog

它基于"自上一个 semver 标签以来"的提交，按 Feature、Fix、Performance Improvement、Breaking Changes 模式匹配并生成 changelog。完整参数清单（来自 cli.ts 的 HELP 文本）如下：

高频场景示例（来自 文档站）：

# 首次引入工具时，一次性重建完整历史（覆盖输出文件） standard-changelog -r 0 # 只生成指定提交范围内的记录 standard-changelog --from v1.0.0 --to HEAD # 预览结果而不写文件 standard-changelog --stdout

这些 CLI 行为都有测试佐证：cli.spec.ts 覆盖了 infile/outfile 的各种组合（追加/覆盖、文件缺失时自动创建）、-k指定 package.json、--context相对/绝对路径、--first-release，以及 context 文件缺失时退出码为 1 并报错等场景。

当前版本的 JS API 用法

standard-changelog是 ESM-only 包，API 入口为 src/index.ts：

import { ConventionalChangelog } from 'conventional-changelog' import angular from 'conventional-changelog-angular' export * from 'conventional-changelog' export class StandardChangelog extends ConventionalChangelog { constructor(cwdOrGitClient: string | ConventionalGitClient) { super(cwdOrGitClient) this.config(angular()) } }

可以清楚看到它的实现方式：继承核心ConventionalChangelog构建器，在构造函数中直接注入angular()预设配置，并完整 re-exportconventional-changelog的所有内容（packagePrefix等辅助函数也可从standard-changelog导入）。

典型用法是惰性构建器链——配置方法只是排队参数并返回this，直到迭代write()或读取writeStream()时才真正访问 git（见 API 文档）：

import { StandardChangelog } from 'standard-changelog' const generator = new StandardChangelog(process.cwd()) .readPackage() for await (const chunk of generator.write()) { process.stdout.write(chunk) }

也可以走流式写法（README 示例）：

const generator = new StandardChangelog() .readPackage() generator .writeStream() .pipe(process.stdout)

继承自ConventionalChangelog的构建器方法包括：loadPreset()（覆盖内置 Angular 预设）、config()、readPackage(path?, transform?)、package(pkg)、readRepository()、repository(infoOrGitUrl)、tags(params)、commits(params, parserOptions?)、options(options)、context(context)、writer(params)、write(includeDetails?)与writeStream(includeDetails?)。其中commits({ from, to })就是 8.0.0 手动提交范围的 API 形态。

在 ConventionalChangelog.ts 中可以看到支撑这些行为的底层实现：构造函数默认releaseCount: 1、append: false（L62-L79）；getCommits()里isManualRange = Boolean(commits.to && (commits.from || commits.to !== 'HEAD'))正是--from/--to的判定逻辑，手动范围下直接按范围取提交，否则按 semver 标签切片（L251-L336）；write()按"取标签 → 定稿 context → 定稿 writer 选项 → 取提交 → 转换 → 写入"的顺序产出每个版本的 Markdown 块（L584-L609）。

结语

从 CHANGELOG 可以读出 standard-changelog 清晰的演进主轴：2016–2020 年以依赖安全维护和 monorepo 联动版本为主；2023 年完成 Node 版本收紧、预设工厂接口统一与 Promise 化三连；2024 年转入 ESM-only；2025–2026 年通过 core/cli 包合并落地 Builder API，并在 8.0.0 将最低 Node 要求提到 22、新增手动提交范围。对于维护既有项目的团队，按上文"破坏性变更"表逐版对照即可规划迁移；对于新项目，则直接以 8.x 的standard-changelog命令与StandardChangelog构建器 API 为起点，配合 Angular 提交约定即可自动维护 CHANGELOG。

• 开发工具
• CLI
• 文档