standard-changelog 深度指南：内置 Angular 规范的 opinionated CHANGELOG 生成器

• 开发工具
• CLI
• 文档

standard-changelog是 conventional-changelog 仓库中一个"开箱即用"的封装：它在核心生成器conventional-changelog的基础上预置了 Angular 提交规范（conventional-changelog-angular preset），无需再安装或选择任何 preset，即可从 git 提交历史生成按 Features / Bug Fixes / Performance Improvements / Breaking Changes 分组的CHANGELOG.md。读完本文，你将掌握它的 CLI 全量参数、JS API 用法、默认行为背后的源码实现，以及如何把它接入真实项目（含 monorepo 场景）。

定位：它和 conventional-changelog 到底差在哪

根据 README，standard-changelog是 "An opinionated approach to CHANGELOG generation using angular commit conventions"（基于 Angular 提交规范的、有主见的 CHANGELOG 生成方式）。两者的关系可以直接从源码看到：

// packages/standard-changelog/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()) } }

在 StandardChangelog 类 中，构造函数做且仅做一件事：把angular()生成的 preset 配置注入基类ConventionalChangelog。这意味着它与conventional-changelog的唯一差异就是"没有 preset 需要安装或选择"——你只需按 Angular 规范写提交信息，工具负责拼装发布说明。

Angular preset 本身的结构见 preset 入口：

export default function createPreset(config) { return { commits: { ignore: config?.ignoreCommits, merges: false // 不纳入 merge 提交 }, parser: createParserOpts(), // 解析提交信息的规则 writer: createWriterOpts(), // 渲染 CHANGELOG 的模板规则 whatBump // 版本升级建议逻辑 } }

其中merges: false意味着 merge 提交不会进入 changelog；parser决定哪些 type 会被分组展示（feature / fix / perf / breaking change 等），writer决定分组标题、链接和排序——这正是 README 中"匹配 Feature、Fix、Performance Improvement 或 Breaking Changes 模式的提交"这一行为的来源。

安装与环境要求

README 给出的安装方式：

# pnpm pnpm add standard-changelog # yarn yarn add standard-changelog # npm npm i standard-changelog

从 package.json 可以确认几个硬性前提：

CLI 用法与默认行为

最简单的调用（README 原样示例）：

standard-changelog

默认行为：读取自上一个 semver tag 以来的提交，把符合 Angular 规范的提交分组渲染后，把新版本区块追加到CHANGELOG.md文件顶部，版本号取自package.json的version字段。

对应仓库文档站给出的输出形态如下（当package.json含repository字段时，版本号和 commit hash 会渲染成 git 托管平台的链接；否则为纯文本短 hash）：

# [1.2.0](https://github.com/acme/app/compare/v1.1.0...v1.2.0) (2026-07-01) ### Features * **api:** add async write() generator ([0f7e2c1](https://github.com/acme/app/commit/0f7e2c1a9d3e4b5c6f7089abcdef0123456789ab)) ### Bug Fixes * **cli:** resolve config path relative to cwd ([a3b9d84](https://github.com/acme/app/commit/a3b9d8472e1f0c9b8a7d6e5f4c3b2a1908f7e6d5)) ### Performance Improvements * **parser:** cache compiled header regex ([c1d2e3f](https://github.com/acme/app/commit/c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0))

这种"版本标题 + 分组小节 + scope 加粗 + 短 hash 链接"的结构来自 Angular preset 的 writer 模板：headerPartial 负责渲染# 版本 (日期)标题，commitPartial 负责渲染每条提交的**scope:** subject (短hash)，并自动处理 issue/PR 引用（如(#123)）的链接化。

CLI 全量参数表

README 提示standard-changelog --help可列出全部参数。以下内容与 CLI 源码中的 HELP 文本 完全一致：

几个高频场景（与文档站 CLI 页面 的示例一致）：

# 预览而不落盘 standard-changelog --stdout # 首次采用：从完整历史重建 CHANGELOG（覆盖输出文件） standard-changelog -r 0 # 等价于 standard-changelog -f # 只生成最近 2 个 release standard-changelog -r 2 --stdout # 限定提交范围 standard-changelog --from v1.0.0 --to v1.1.0 --stdout # monorepo：按 tag 前缀 + 目录隔离 standard-changelog -t "api-v" --commit-path packages/api --stdout # Lerna 风格 tag（形如 api@1.2.0） standard-changelog -l api --commit-path packages/api --stdout # 自定义输入/输出文件（--outfile 默认等于 --infile） standard-changelog -i HISTORY.md -o RELEASES.md

--append（-a）用于 changelog 采用"旧→新"排序、新 release 应写到文件底部的仓库。

默认值与关键机制的源码印证

上面参数表的"默认值"列并非凭空而来，可以直接在 ConventionalChangelog 构造函数 中看到初始参数：

this.params = Promise.resolve({ options: { append: false, releaseCount: 1, formatDate, transformCommit: defaultCommitTransform }, commits: { format: '%B%n-hash-%n%H%n-gitTags-%n%d%n-committerDate-%n%ci', merges: false } })

即releaseCount: 1、append: false，以及提交记录中显式排除 merge 提交（与 preset 中的merges: false双重保证）。

另外几个值得注意的实现细节（均来自 ConventionalChangelog.ts）：

• 版本号来源与链接回退：readPackage()会向上查找最近的package.json，取其version作为版本；若package.json没有repository字段，会回退读取git remote origin的 URL 来生成 commit/compare 链接（见 getPackageJson）。没有任何 repository 信息时 changelog 依然会生成，只是版本号和 hash 为纯文本。
• -r 0的覆盖语义：releaseCount为 0 时from置空，即从仓库最早提交开始重新生成所有 release，并覆盖输出文件——这就是"重新生成整个历史"的实现路径（见 getCommits）。
• Unreleased区块：当package.json的 version 与最新 tag 相同、但 tag 之后又有新提交时，--output-unreleased（或 API 的outputUnreleased）会把这些提交渲染到# Unreleased标题下（见 finalizeContext）。
• --config/--context的加载方式：CLI 通过 loadDataFile 加载这两个文件——.json走JSON.parse，其他扩展名按 ESM 模块动态import并取其default导出。

JS API 用法

README 给出的最小示例（注意：仓库文档与测试中实际以process.cwd()显式传入工作目录，StandardChangelog的构造参数是必填的）：

import { StandardChangelog } from 'standard-changelog' const generator = new StandardChangelog(process.cwd()) .readPackage() generator .writeStream() .pipe(process.stdout)

API 要点（依据 JS API 文档 与基类实现）：

• 构造参数接受工作目录字符串或ConventionalGitClient实例：new StandardChangelog(new ConventionalGitClient('/path/to/repo'))；
• 所有配置方法（readPackage、tags、commits、options、context、writer等）只把参数排队并以this返回，惰性求值——在迭代write()或读取writeStream()之前不会触碰 git，因此可以任意顺序链式调用；
• write(includeDetails?)是 async generator，每个 release 产出一个 chunk；传true时产出结构化对象{ log, keyCommit }（log为该 release 的 Markdown，keyCommit为标识该 release 的提交）；
• writeStream(includeDetails?)用Readable.from(...)把同样的输出包装成 Node.js 可读流，方便pipe到文件（见 writeStream 实现）；
• 构造函数内config(angular())之后，仍可再调用loadPreset()或config()覆盖Angular 默认配置，适合"在 Angular 默认值上做少量定制"的场景；
• standard-changelog通过export * from 'conventional-changelog'完整转发基类导出，因此ConventionalChangelog、packagePrefix等辅助函数也可直接从standard-changelog导入。

monorepo 中"按包生成发布说明"的典型写法（文档站示例模式）：

import { StandardChangelog, packagePrefix } from 'standard-changelog' const changelog = new StandardChangelog(gitClient) .commits({ path: projectPath }) // 只统计该包目录下的提交 .tags({ prefix: packagePrefix('my-package') }) // 匹配 my-package@1.2.0 形式的 tag .readRepository() .context({ version: nextVersion }) // 即将发布的版本号 .writer({ preamblePartial }) // 可选：release 区块前言模板 for await (const section of changelog.write()) { // 将 section 追加到该包的 CHANGELOG.md }

测试如何验证这一封装

仓库自带的测试 index.spec.ts 完整演示了这条链路的最低验证标准：初始化一个临时 git 仓库并创建一条feat: first commit提交，然后断言StandardChangelog生成的 changelog 包含Features分组：

it('should generate angular changelog', async () => { const log = new StandardChangelog(testTools.cwd) .readPackage() .write() const chunks = await toArray(log) expect(chunks[0]).toContain('Features') expect(chunks.length).toBe(1) })

这恰好印证了 README 的核心承诺：无需任何 preset 安装步骤，feat:类型的提交会被自动归入Features小节。

适用前提与限制小结

1. 提交必须遵循 Angular/conventional 规范：feat:、fix:、perf:等 type 之外的提交（以及 merge 提交）不会进入输出；不符合规范的历史提交需要配合--config覆盖 parser 或改用其他 preset（-p）。
2. 依赖 semver tag：默认范围由"上一个 semver tag"决定；若仓库没有 tag，可显式指定--from/--to或用-r 0生成完整历史。
3. 环境要求：Node.js ≥ 22、纯 ESM 项目（依赖包为 ESM-only）。
4. -r 0会覆盖输出文件，首次使用或迁移时请知悉。
5. 链接渲染依赖package.json的repository字段（缺失时回退git remote origin）；不支持的主机平台只会产生警告而不阻断生成（见 write 中的 warn 逻辑）。

更完整的 CLI 示例与 API 参考可继续查看仓库内的 CLI 文档、JS API 文档 与 Introduction。

• 开发工具
• CLI
• 文档