release-it 集成 auto-changelog:自动生成 CHANGELOG.md 的完整实战指南
release-it 集成 auto-changelog:自动生成 CHANGELOG.md 的完整实战指南
release-it 默认基于 git log 生成简洁的 changelog,用于发布预览与版本选择;当项目需要更丰富、带标题与分组的 changelog 时,社区工具 auto-changelog 是官方推荐的搭档。本文以仓库内 docs/recipes/auto-changelog.md 为主干,结合 release-it 源码中 changelog 的生成时机、钩子调用链与内置模板,完整讲解安装、配置、模板定制,以及无 package.json 项目的 Keep a Changelog 兼容方案,帮助你搭建一条"预览 → 生成 → 提交"全自动化的 changelog 流水线。
一、为什么需要 auto-changelog:release-it 的 changelog 机制概览
release-it 在每次发布前都会生成一份 changelog,主要用途有二:一是发布流程启动时以 Changelog: ... 形式打印预览(由 lib/index.js 中的 getChangelog() 调用与 log.preview 完成),帮助确认本次发布包含哪些提交;二是该输出随后被用作 GitHub / GitLab Release 的 release notes(见 docs/github-releases.md 与 docs/gitlab-releases.md)。
默认的 changelog 命令定义在 git.changelog 选项中,默认值为:
git log --pretty=format:"* %s (%h)" ${from}...${to}
该默认值同时记录在 config/release-it.json 与 schema/git.json 中,输出形如 * Add feature (a1b2c3d)——每行一条提交,只有主题与短哈希,没有分组、标题与日期。而 auto-changelog 基于 Handlebars 模板可以生成带版本标题、merge/fix/commit 分区、breaking change 标记的富文本 changelog,这正是 docs/changelog.md 推荐将它作为 release-it 搭档的原因。
源码视角:changelog 在哪个环节生成
git.changelog 命令的实际执行在 Git 插件的 getChangelog() 方法中,见 lib/plugin/GitBase.js:
- 执行时注入模板变量
context = { latestTag, from: latestTag, to: 'HEAD' },命令中出现的${from}、${to}、${latestTag}会被替换为实际值; - 非增量发布(如
release-it不带版本参数)且最新 tag 之后没有新提交时,from会回退到第二新的 tag、to变为latestTag^1,保证 changelog 不为空; - snapshot 发布时 changelog 直接返回空字符串(快照通常不生成 changelog);
- 当仓库还没有任何 tag(
context.from为空)且命令中包含${from}时,自动回退到内置的git log命令,避免命令因空变量出错。
因此任何自定义的 git.changelog 命令都必须满足同一个硬性约束:把 changelog 输出到 stdout(见 docs/changelog.md)。这正是下面配置中 --stdout 参数的由来。
二、安装 auto-changelog
在项目根目录执行:
npm install --save-dev auto-changelog
将 auto-changelog 安装为开发依赖,随后便可在配置文件中通过 npx auto-changelog ... 调用(无 package.json 的项目请跳过本步,直接看第四节)。
三、核心配置:git.changelog 与 hooks.after:bump 双管齐下
在 release-it 配置文件(如 .release-it.json、package.json 的 release-it 字段等,配置文件的查找位置见 docs/configuration.md)中加入:
{
"git": {
"changelog": "npx auto-changelog --stdout --commit-limit false --unreleased --template https://raw.githubusercontent.com/release-it/release-it/main/templates/changelog-compact.hbs"
},
"hooks": {
"after:bump": "npx auto-changelog -p"
}
}
这是一份分工明确的配置,两条命令分别作用于发布流程的不同阶段:
1. git.changelog:版本选择之前的预览命令
该命令在发布流程启动、版本尚未确定时执行(git-cliff 配方中也明确指出这一点,见 docs/recipes/git-cliff.md),所以它渲染的是尚未发布的提交:
--stdout:把生成的 changelog 输出到 stdout,供 release-it 捕获为预览文本与后续 release notes——这是git.changelog命令的硬性要求;--commit-limit false:不限制纳入 changelog 的提交数量,避免默认 3 条限制导致预览不完整;--unreleased(短选项-u):只渲染尚未打 tag 的提交,与"版本选择前"的时机吻合;--template <URL>:指定 Handlebars 模板。这里指向 release-it 仓库维护的 templates/changelog-compact.hbs,也可以替换为项目内的本地路径(如--template ./changelog-compact.hbs),便于团队自行维护模板。
2. hooks.after:bump:版本确定之后写盘
after:bump 钩子在新版本号确定、各文件版本号完成更新之后执行,此时 CHANGELOG.md 的更新会随 release 提交一并提交。这正是 docs/changelog.md 推荐的在 after:bump 中自动更新 changelog 文件的原因。npx auto-changelog -p 在此阶段生成包含本次发布版本的完整 CHANGELOG.md。若项目不维护 CHANGELOG.md 之类的文件,可以省略该钩子(仅保留 git.changelog 用于预览与 release notes)。
3. 底层调用链印证
自定义命令与默认命令走的是同一条代码路径:release-it 在 lib/index.js 通过 reduceUntil 依次调用各插件的 getChangelog();Git 插件的实现位于 lib/plugin/GitBase.js,它最终通过 this.exec(changelog, { context, options }) 在 shell 中执行配置的命令。因此只要命令输出合法、包含模板变量(${from}、${to})时存在对应 tag,行为就与默认 git log 命令一致,release-it 的 --changelog 模式(见 lib/cli.js)与发布预览功能均可直接复用。
测试 test/git.init.js 也验证了这一机制:构造 tag 与提交后调用 gitClient.getChangelog(),断言输出形如 * Add file (\w{7}) 的逐行提交列表,与默认模板中 %h 短哈希的格式一一对应。
四、模板详解:changelog-compact.hbs 是如何工作的
配置中的模板 templates/changelog-compact.hbs 本质上是 auto-changelog 默认 compact 模板的简化拷贝:去掉了顶部标题,并在 releases 迭代中加了 {{#if @first}} 块,使只有第一个 release(即 unreleased 部分)的提交被渲染,与 --unreleased 标志配合实现"仅预览未发布提交"的效果。完整模板如下:
{{#each releases}}
{{#if @first}}
{{#each merges}}
- {{{message}}}{{#if href}} `#{{id}}`{{/if}}
{{/each}}
{{#each fixes}}
- {{{commit.subject}}}{{#each fixes}}{{#if href}} `#{{id}}`{{/if}}{{/each}}
{{/each}}
{{#each commits}}
- {{#if breaking}}**Breaking change:** {{/if}}{{{subject}}}{{#if href}} `{{shorthash}}`{{/if}}
{{/each}}
{{/if}}
{{/each}}
逐段解读其逻辑:
{{#each releases}}遍历所有 release 记录(auto-changelog 按 tag 切分历史);{{#if @first}}是 Handlebars 的索引判断,确保只处理最新(未发布)的那一段;merges段:渲染每个 merge 提交的message,若存在对应链接(href,auto-changelog 根据远程仓库自动生成提交/PR 链接),则追加`#{{id}}`形式的编号引用;fixes段:渲染修复类提交的主题commit.subject,同样附加链接;commits段:渲染普通提交,其中breaking为真时前置**Breaking change:**加粗标记,并以{{shorthash}}短哈希附上提交链接——breaking change 的识别能力正是相比默认git log输出更丰富的点之一;{{{subject}}}使用三花括号:不对内容做 HTML 转义,避免提交信息中的特殊字符被模板引擎改写。
若你希望自定义 changelog 样式(例如增加作者、日期或分组标题),只需复制该模板到项目内修改,并将 --template 指向本地文件即可,无需改动 release-it 配置的其他部分。
五、无 package.json 项目:Keep a Changelog 兼容方案
某些项目没有 package.json(无法通过 npm 管理依赖),但仍需要生成符合 Keep a Changelog,配置如下:
{
"git": {
"changelog": "npx auto-changelog --stdout --commit-limit false --unreleased --template https://raw.githubusercontent.com/release-it/release-it/main/templates/changelog-compact.hbs"
},
"hooks": {
"after:bump": "npx auto-changelog --commit-limit false --template https://raw.githubusercontent.com/release-it/release-it/main/templates/keepachangelog.hbs"
}
}
与第三节配置相比,本方案的差异点:
git.changelog保持不变:预览仍用 compact 模板渲染 unreleased 提交;after:bump换成 Keep a Changelog 模板:该模板会输出完整历史(不再加--unreleased),而非仅本次发布——这正是CHANGELOG.md文件应有的结构。
仓库内 templates/keepachangelog.hbs 的骨架为:顶部 # Changelog 标题,随后按 release 迭代输出 ## [版本号] (日期) 小节(有链接时标题包裹为链接,isoDate 输出发布日期),再依次列出 summary、merges、fixes、commits 分组。由于 auto-changelog 通过 npx 运行,无 package.json 的项目需保证 Node 环境可用并事先安装好 auto-changelog CLI;若无法联网拉取远程模板,可把两个 .hbs 模板文件复制到项目内改为本地路径引用。
六、changelog 的更多下游用途与相近方案
了解 changelog 的生成后,值得留意它在下游的复用,这能让配置发挥更大价值:
- GitHub/GitLab Release notes:
git.changelog的输出默认即为 GitHub / GitLab Release 的 release notes;需要针对 release 定制内容时可用github.releaseNotes/gitlab.releaseNotes覆盖(见 docs/github-releases.md)。注意 release notes 命令在发布前调用,此时${version}已可用(见 docs/recipes/git-cliff.md); - 自动评论已解决 issue/PR:GitHub 插件会从 changelog 文本中提取 7 位以上的短哈希(正则
/\((<a href="https://link.gitcode.com/i/dd9c1c21bd0a552f2d124421d210abbf" target="_blank">a-f0-9]{7,})\)/i,见 [lib/plugin/github/util.js),配合github.comments.submit自动在本次发布解决的 issue 与合入的 PR 上留言,见 lib/plugin/github/GitHub.js。这要求 changelog 行中包含(shorthash)形式的提交哈希,使用 compact 模板时天然满足; - 其他 changelog 方案:若项目遵循 Conventional Commits,官方另有
@release-it/conventional-changelog与@release-it/keep-a-changelog插件,可分别自动生成 conventional changelog 与维护 "Unreleased" 段;git-cliff也有独立配方 docs/recipes/git-cliff.md。各方案对比与选择建议见 docs/changelog.md。
最后提醒两点可验证的细节:其一,git.changelog 亦可在命令行覆盖(如 --git.changelog="npx auto-changelog ...",参数解析见 lib/args.js),便于在 CI 或临时场景切换模板;其二,发布长 changelog 项目时可用 --quiet(对应 quiet: true)隐藏预览输出(见 docs/changelog.md),它不影响 --changelog 模式——该模式会直接打印 changelog 并退出(见 lib/index.js),是验证自定义命令输出的最快捷途径。