conventional-changelog 8.x 版本演进全解：从 CHANGELOG 看 Builder API、CLI 参数与生成流程

开发工具CLI文档【免费下载链接】conventional-changelogGenerate changelogs and release notes from a projects commit messages and metadata.项目地址https://gitcode.com/gh_mirrors/co/conventional-changelog点击查看免费下载conventional-changelog的核心职责只有一句话从项目的 commit 信息和 git 元数据生成变更日志。本仓库根目录下的packages/conventional-changelog/CHANGELOG.md完整记录了该包从 0.0.2 到 8.1.3 的全部发布历史它不仅是一份版本清单更是一部浓缩的架构演进史从最初基于 stream 的脚本工具到 7.0.0 合并 core 与 CLI 并引入 Builder API再到 8.0.0 用渲染函数替换 Handlebars 模板、将 Node.js 要求提升到 22。本文以这份 CHANGELOG 为骨架结合 CHANGELOG.md 中的条目与 ConventionalChangelog.ts、cli/index.ts 等源码完整还原 8.x 版本的能力、参数与底层实现读完你可以直接上手 Builder API 与 CLI 的每一个参数并理解每条版本条目背后对应的代码行为。版本演进时间线从 CHANGELOG 读出的关键节点CHANGELOG 中所有条目按 SemVer 组织#一级标题表示重大版本major##二级标题表示 minor/patch每条都带有发布日期。把噪声条目大量 Version bump only过滤掉后真正影响使用者 API 的节点如下版本日期性质核心变化8.0.02026-06-26majorHandlebars 模板替换为渲染函数要求 Node.js 22支持手动 commit 范围--from/--to8.1.02026-07-09minorCLI 参数解析由meow换成argue-cli8.1.12026-08-06patchskipUnstable开启时不再为不稳定标签生成 section8.1.22026-08-10patch使用当前 host 的 url 路径模板8.1.32026-08-12patch把conventional-commits-filter补进 dependencies对应 npm/cli 的依赖问题7.2.12026-06-22patch改进 changelog 生成时的版本 tag 解析7.2.02026-03-01minor各 preset 统一换行格式改用 simple-libs 的 utilsgithttps 正则支持多级 GitLab subgroup7.1.02025-06-07minorloadPreset新增可选loader参数7.0.02025-05-19majorconventional-changelog-core 与 conventional-changelog-cli 合并进 conventional-changelog全新的 Builder API 与 CLI 参数6.0.02024-04-26major要求 Node 18除 gulp-conventional-changelog 外全部改为 ESM-only5.0.02023-08-26major要求 Node 16所有 preset 统一导出 preset config 工厂函数preset-loader 提供loadPreset/createPresetLoader4.0.02023-06-05major要求 Node 14尽可能去除 lodash 依赖3.1.02019-04-10minor新增 conventionalcommits preset、preMajor配置项1.0.02016-02-05major拆分为多个独立模块preset 各自成包0.1.0-alpha.12015-06-24首版模块重写API 不再向后兼容几个从时间线中可以读出的演进规律7.0.0 是最近一次结构性大重构。CHANGELOG 中该条的 BREAKING CHANGES 原文为「conventional-changelog-core and conventional-changelog-cli packages are merged to conventional-changelog; new builder API and updated CLI flags」。也就是说今天你使用的conventional-changelog同时是生成器库和 CLI 入口core与cli两个子包已经并入。当前 package.json 印证了这一点publishConfig.bin指向dist/cli/index.js而exports指向构建后的dist/index.js一个包内既有库 API 又有可执行文件。8.0.0 的三条 BREAKING 特性「replace handlebars templates with render functions」「require node 22」「support manual commit ranges」。前一条主要影响自定义模板的 preset 作者后两条直接体现在engines.node: 22见 package.json与--from/--to两个新 CLI 参数上。8.1.3 补依赖条目值得注意它把conventional-commits-filter显式加进 dependencies并在条目中交叉引用了 npm 官方 CLI 的 issue。当前 package.json 的依赖列表中确实同时包含conventional-changelog-writer、conventional-commits-filter、conventional-commits-parser、conventional-changelog-preset-loader、conventional-changelog/git-client等 workspace 包以及argue-cli8.1.0 引入的 CLI 解析库和fd-package-json7.2.0 起用于查找 package.json。7.0.0 的 Builder APICHANGELOG 重构条目的当前形态7.0.0 条目所说的「new builder API」是理解 8.x 全部代码的钥匙。入口类ConventionalChangelog定义在 ConventionalChangelog.ts构造函数接受工作目录或一个已构造好的ConventionalGitClient并内置一组默认参数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 } })从源码结构看commits.format就是最终传给git log的输出格式串先输出完整 body%B再依次分隔 hash、git tag、committer date——这正是后续defaultCommitTransform能拿到gitTags和committerDate的来源。Builder 链式方法一览ConventionalChangelog提供了一组返回this的链式配置方法每个方法对应Params的一个维度见 types.ts方法作用对应参数维度readPackage(path?, transform?)读取 package.json可用fd-package-json就近查找可选传入转换函数同时解析 repository 为HostedGitInfopackage/repositorypackage(pkg)直接提供 package.json 数据对象packagereadRepository()从 git 的remote.origin.url读取仓库信息repositoryrepository(infoOrGitUrl)直接提供仓库 URL 或HostedGitInforepositoryloadPreset(preset, loader?)按名称或对象/工厂加载 preset 配置loader为 7.1.0 新增的自定义模块加载器全部 preset 维度config(config)直接提供 preset 配置对象tags/commits/parser/writer全部 preset 维度options(options)设置生成器选项append、releaseCount等optionscontext(context)设置写入模板上下文变量contexttags(params)设置 semver tag 读取参数prefix、skipUnstabletagscommits(params, parserOptions?)设置 commit 读取参数from/to/path与 parser 选项commits/parserwriter(params)设置 conventional-changelog-writer 选项writerwrite(includeDetails?)执行生成返回AsyncGeneratorstring或AsyncGeneratorDetails—writeStream(includeDetails?)将write()包装为 Node 可读流—所有这些方法最终汇入私有方法composeParamsConventionalChangelog.ts它把新参数与旧参数按options/context/tags/commits/parser/writer/repository七个维度浅合并且package遵循「先设置的优先」规则prevParams.package || params.package。因此链式调用的顺序有意义先loadPreset再config后者会覆盖前者同维度字段。loadPreset的实现ConventionalChangelog.ts体现了 CHANGELOG 7.1.0 与 5.0.0 两条演进loadPreset(preset, loader?) { const loadPreset loader ? createPresetLoader(loader) : defaultLoadPreset const config loadPreset(preset).then((config) { if (!config) { throw Error(Preset is not loaded or have incorrect exports) } return config }) this.composeParams(config) return this }5.0.0 的「unified presets interface」要求 preset 导出 config 工厂函数加载失败会抛出明确的Preset is not loaded or have incorrect exports错误而不是静默降级7.1.0 的第二个参数loader允许注入自定义模块加载器典型场景服务端无法用require解析 preset 包名时这正是 CHANGELOG 中「addloaderoptional argument toloadPresetmethod」条目的落地代码。README 中的最小可运行示例README.mdimport { ConventionalChangelog } from conventional-changelog const generator new ConventionalChangelog() .readPackage() .loadPreset(angular) generator .writeStream() .pipe(process.stdout)write()的内部流水线write()方法ConventionalChangelog.ts是整个生成过程的核心其执行顺序为getHostOptions(repository, context)—— 根据仓库 host 或 context 中的host字段匹配内置 host 选项github/gitlab/bitbucket见 hosts/index.ts。host 选项会提供issue/commit/compareURL 模板以及referenceActions如close、fixes、resolves和issuePrefixes如#、gh-例如 github.ts 中列出的 9 个参考动作。匹配不到时会通过options.warn输出Host is not supported: ...警告getSemverTags()—— 通过ConventionalGitClient.getSemverTags收集当前分支的 semver 标签finalizeContext()—— 组装最终模板上下文注入packageData、version、gitSemverTags再叠加repository解析出的repoUrl/host/owner/repository以及 host 选项提供的issue/commit/compare模板。若开启outputUnreleased且context.version恰好等于最后一个 tag则把version改写为UnreleasedfinalizeWriterOptions()—— 生成 writer 的finalizeContext回调这是 8.1.1 修复涉及的核心逻辑它根据keyCommit.gitTags匹配versionTagRegex确定currentTag再从semverTags数组定位previousTag没有 previous tag 时回退到首/末 commit hash当version Unreleased且没有 currentTag 时按tags.prefix或guessNextTag()推断linkCompare在两个 tag 都存在时默认置为truegetCommits()—— 拉取并解析 commit 流下一节详述transformCommits()—— 对每个 commit 执行transformCommit默认defaultCommitTransformwriteChangelog()—— 交给 conventional-changelog-writer 按 preset 模板渲染。注意第 6 步的defaultCommitTransformutils.ts正是 CHANGELOG 8.1.1 条目的直接受益者它在从gitTags里匹配版本号时会执行!(tags?.skipUnstable isPrereleaseVersion(version))过滤——即skipUnstable开启时x.x.x-alpha.1、x.x.x-rc.2这类 pre-release 标签不会被打上version字段从而不再被 writer 当作版本分节点生成 section。tag 读取端ConventionalGitClient.ts也有一模一样的过滤条件两侧共同保证了 8.1.1 修复「do not generate sections for unstable tags when skipUnstable is set」的完整性。getCommits()releaseCount、手动范围与 append 的取值逻辑getCommits()ConventionalChangelog.ts是 8.0.0「support manual commit ranges」条目的主要落点。其判断逻辑可以概括为手动范围判定isManualRange Boolean(commits.to (commits.from || commits.to ! HEAD))。只要显式传了toCLI 的--to并且满足给了from或to不是HEAD就走单一git log from..to路径完全绕过 semver tag常规路径根据releaseCount计算from——from releaseCount ? semverTags[releaseCount - 1] : undefined。releaseCount 1默认即「上一个 tag 到 HEAD」releaseCount 0即从头生成全部历史对应 CLI 的--first-release与--release-count 0分 tag 段拉取常规路径会构造reverseTags所有 semver tag 倒序 HEAD相邻 tag 两两一组分别调用gitClient.getCommits({ from, to })再按需反转合并。这样做的好处是每段 commit 天然按 tag 边界分组writer 可以据此插入版本标题options.append为 true 时reverse置位让新 release 排在旧 release 之前降级路径外层try会先执行gitClient.verify(HEAD)若仓库状态不可用例如空仓库catch 分支退化为不带 tag 范围的getCommits(params)。Options类型types.ts对上述参数给出了完整文档化定义字段类型默认值说明resetbooleanfalse是否重置忽略 tag 边界从头生成appendbooleanfalse新 release 追加到旧 release 之前releaseCountnumber1从最近的 release 起生成几个版本0表示全量重新生成outputUnreleasedboolean—当context.version等于最后一次 release 时改写为UnreleasedtransformCommitCommitTransformFunctiondefaultCommitTransformparser 之后、writer 之前对每个 commit 的转换钩子返回null可丢弃该 commitwarn/debugLogger—分别绑定到core/parser与writer/git-client命名空间的日志器formatDate(date) stringformatDate自定义日期格式化函数其中transformCommit是自定义 preset 最常用的钩子例如过滤 merge commit、给breaking字段打补丁等。返回null或其 Promise 解析为null时该 commit 不会进入 writer见transformCommits()中的if (transformed) yield transformedConventionalChangelog.ts。CLI 参数全表从 8.0.0 新标志到 8.1.0 的解析器更换8.0.0 之后 CLI 标志全面重写8.1.0 又把参数解析库从meow换成了argue-cli。当前 CLI 入口为 cli/index.ts帮助文本中列出的完整参数如下与 cli/cli.ts 的readFlags定义一一对应参数短选项类型默认值说明--infile-istringCHANGELOG.md读取已有 CHANGELOG 的文件--outfile-ostringinfile写入目标文件--stdout—flag—结果输出到标准输出--preset-pstring—使用的 preset 名称--pkg-kstring最近的 package.jsonpackage.json 路径--append-aflagfalse新 release 追加到旧 release 之前--first-release-fflag—首次生成 CHANGELOG等价releaseCount: 0--release-count-rnumber1生成几个最近 release0表示全量重新生成并覆盖 outfile--skip-unstable—flag—跳过不稳定标签如x.x.x-alpha.1、x.x.x-rc.2--output-unreleased-uflag—输出 Unreleased 区段--verbose-vflagfalse调试输出打印各命名空间日志--config-nstring—配置文件路径提供tags/commits/parser/writer段--context-cstring—模板上下文的 JSON 文件--lerna-package-lstring—为指定 lerna 包生成 changelogscope/pkg1.0.0映射为 tag prefix--tag-prefix-tstring—读取 tag 时使用的 tag 前缀--commit-path—string—只统计指定目录下的 commit--from—string—手动 commit 范围的起点tag 或 sha8.0.0 新增--to—string—手动 commit 范围的终点tag 或 sha8.0.0 新增参数到生成器的映射发生在runProgram()cli/cli.ts中顺序即优先级体现先readPackage(pkg)若有 preset 则loadPreset随后依次载入--config文件映射到generator.tags/commits/writer与--context文件generator.context最后才是命令行标志解析出的options、tags、commits参数——后者通过 options.ts 的三个解析函数组装其中--first-release被转换为releaseCount: 0--lerna-package通过packagePrefix()转换为 tag prefix。--verbose则会给生成器注入打印[namespace]: payload的debug/warn回调。几个与 7.0.0/8.0.0 重构直接相关的行为细节infile 与 outfile 同文件且非 append时CLI 会先把新内容全部缓冲再拼接旧内容写入cli/cli.ts保证「新 release 在上、旧内容在下」的覆盖语义releaseCount ! 0且 infile 不存在时仅提示警告verbose 模式下不会报错中断releaseCount 0时完全忽略 infile 内容直接覆盖生成全量历史——这正是帮助文本中「If 0, the whole changelog will be regenerated and the outfile will be overwritten」的来源--from/--to走 8.0.0 引入的手动范围路径上一节此时 semver tag 不再参与 commit 拉取适合「只给某个 tag 区间补一份记录」的场景。README 给出的最常用调用README.mdconventional-changelog -p angular「This willnotoverwrite any previous changelogs」指的是默认行为下已发布的版本记录会被保留在 infile 之后。8.1.x 三个 patch 的源码印证8.1.x 是纯修复序列每一条都能在源码中找到对应物8.1.3把 conventional-commits-filter 补进 dependencies条目原文「add conventional-commits-filter to dependencies」。package.json 的dependencies中现在明确列有conventional-commits-filter: workspace:^。从ConventionalChangelog.ts的源码结构看writer 链路writeChangelog内部负责 revert 过滤依赖此前是经由 workspace 间接提供的显式声明后避免了 npm 打包时依赖缺失的问题条目中交叉引用了 npm/cli 的相关 issue。8.1.2使用当前 host 的 url 路径模板条目原文「use current host url paths」。host 选项中的issue/commit/compare是 URL 模板如 github.ts 中的commit、comparefinalizeContext()会把它们写进finalContextwriter 模板据此渲染版本对比链接与 commit 链接修复后各 host 的模板路径与当前仓库 URL 结构保持一致。8.1.1skipUnstable 时不再生成不稳定 tag 的 section条目原文「do not generate sections for unstable tags when skipUnstable is set」。如前所述修复点在两处defaultCommitTransform的matchSemverTag谓词utils.ts与 tag 读取端getSemverTags的 pre-release 过滤ConventionalGitClient.tsgit-client 的测试ConventionalGitClient.spec.ts也以skipUnstable: true覆盖了x.x.x-alpha.1与x.x.x-rc.2场景。环境要求与安装前提Node.js 版本8.0.0 起要求 Node 22当前 package.json 为engines: { node: 22 }。此前的门槛演进为6.0.0 要求 Node 18并转 ESM-only、5.0.0 要求 Node 16、4.0.0 要求 Node 14这些在 CHANGELOG 各 major 条目的 BREAKING CHANGES 中均有记录模块形态6.0.0 起除 gulp-conventional-changelog 外全部为 ESM-only当前包type: moduleAPI 以import { ConventionalChangelog }方式使用安装方式README.mdconventional-changelog 需要搭配一个 preset 一起安装例如# pnpm pnpm add conventional-changelog conventional-changelog-angular # yarn yarn add conventional-changelog conventional-changelog-angular # npm npm i conventional-changelog conventional-changelog-angular本仓库内的 preset 包括 conventional-changelog-angular 与 conventional-changelog-conventionalcommits均遵循 5.0.0 之后统一的「导出 preset config 工厂函数」接口。这份 CHANGELOG 本身就是 conventional-changelog 的产物一个容易忽略的事实packages/conventional-changelog/CHANGELOG.md 本身就是用本工具按 Conventional Commits 规范从 git 历史生成的——条目里### Features、### Bug Fixes、### BREAKING CHANGES的分节、每条附带的短 commit hash都是 conventional-changelog-writer 按 preset 模板渲染的典型输出。这也解释了为什么 4.0.0 到 7.2.1 之间的多数条目只有「Version bump only」monorepo 中其他包发布时该包版本号会随 workspace 同步递增。若要复现这份 changelog等价于在当前仓库运行conventional-changelog -p conventionalcommits -i CHANGELOG.md具体 preset 以仓库自身的发布脚本为准此处仅说明用法形态。小结以 CHANGELOG.md 为主线的阅读结论是conventional-changelog 8.x 是 7.0.0 大合并后的稳定化阶段——8.0.0 完成模板引擎Handlebars → 渲染函数与运行环境Node 22升级并带来--from/--to手动范围这一新能力8.1.0 换了更轻量的 CLI 解析器argue-cli8.1.18.1.3 依次修复了不稳定标签分节、host URL 路径模板与依赖声明三个具体问题。对使用者而言核心操作面收敛为两块CLI 侧以-p preset -i/-o 文件为骨架配合--release-count/--first-release/--skip-unstable/--output-unreleased/--from/--to控制生成范围API 侧以new ConventionalChangelog(cwd).readPackage().loadPreset(preset).write()/writeStream()为骨架通过options/tags/commits/writer/context等链式方法精细调参。每个参数的语义都能在上面列出的源码位置找到权威定义。赞分享开发工具CLI文档【免费下载链接】conventional-changelogGenerate changelogs and release notes from a projects commit messages and metadata.项目地址https://gitcode.com/gh_mirrors/co/conventional-changelog点击查看免费下载相关推荐解读 Sanity Studio 6.x CHANGELOG从 Conventional Commits 到版本演进与源码追踪实战解读 Sanity Studio 6.x CHANGELOG从 Conventional Commits 到版本演进与源码追踪实战 导读 本文以仓库根目录 CCMS前端Editor.js 版本演进全解析从 CHANGELOG 看 2.x 系列核心能力、API 与关键修复Editor.js 版本演进全解析从 CHANGELOG 看 2.x 系列核心能力、API 与关键修复 导读本文以仓库内 docs/CHANGELOG.md前端富文本UI组件Janus WebRTC Server 版本演进全解析从 CHANGELOG 看 v1.x 架构迭代与插件生态Janus WebRTC Server 版本演进全解析从 CHANGELOG 看 v1.x 架构迭代与插件生态 Janus 是一个开源的、通用目的的 WebR音视频后端即时通讯上一篇BNB Smart ChainbscCHANGELOG 深度解读从 Pasteur 硬分叉到版本升级运维指南下一篇从0到1理解Fqsen类phpDocumentor/ReflectionCommon中的命名空间魔法创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考