release-it 集成 auto-changelog:自动生成 CHANGELOG.md 的完整实战指南

原创2026-09-24 17:06:121,820 阅读
文章标签:开发工具DevOps

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),是验证自定义命令输出的最快捷途径。

登录后查看全文
release-it