前端 changeLog 自动化生成实战：用 conventional-changelog + standard-version 打通 git-commit 规范

1. 为什么前端团队需要自动化 changeLog先说结论changeLog不是给领导看的装饰品它是团队协作的“时间轴”。当项目迭代到第 30 个版本有人问“这个fix到底修了哪个线上问题”如果只能靠翻 git log 一条条猜那基本等于没有记录。前端项目尤其明显package.json里的版本号天天变但CHANGELOG.md往往还停留在“初始化项目”那一行。我见过太多团队的做法是发版前手动回忆这周改了啥然后写一段“修复若干问题、优化部分体验”。这种 changeLog 对排查问题毫无价值。真正有用的 changeLog 应该由git-commit规范驱动提交信息写对了工具自动帮你归类成feat、fix、perf这些区块版本号也能按语义化规则自动递增。这篇要打通的就是这条链路从commitlint约束提交格式到conventional-changelog生成日志再到standard-version一键完成“升版本 打 tag 写 CHANGELOG”。适合正在做前端工程化、准备落地规范化发布流程的同学。下面所有配置都可以直接复制最后会用一个真实提交验证整条链路跑通。2. 前置准备TaoToken 与项目环境在动手之前先把两件事准备好一个是模型能力入口一个是本地 Node 环境。如果你在配置过程中遇到报错或者想让模型帮你解释某段commitlint规则、生成一份standard-version配置骨架可以直接用 TaoToken 的模型对话能力来辅助排查。它的入口是https://taotoken.net/api配合 API Key 就能在脚本或工具里调用。对于长期做前端工程化、需要反复调试配置的团队Coding Plan 会更划算适合把这类“配置 排障”的重复动作沉淀成固定流程。本地环境要求不高Node.js 16 以上standard-version对 Node 版本有要求太低会报optional chaining语法错误项目已经用 git 管理并且至少有一次提交包管理器用 npm / yarn / pnpm 都行下面统一用 npm 演示先确认 git 状态干净避免生成 changeLog 时把未提交的改动混进去git status git log --oneline -5如果git log里全是“update”“fix bug”这种提交别急后面会先立规矩再生成。3. 可复制配置commitlint standard-version 骨架3.1 安装依赖一次性把需要的包装上。这里分两类提交规范类和日志生成类。npm install --save-dev \ commitlint/cli \ commitlint/config-conventional \ husky \ conventional-changelog \ conventional-changelog-cli \ standard-version \ conventional-changelog-gitmoji-config简单说下各自职责commitlint/cliconfig-conventional负责校验提交信息husky把校验挂到 git hook 上conventional-changelog-cli负责生成日志standard-version负责升版本、打 tag、写 CHANGELOG 一条龙conventional-changelog-gitmoji-config是给喜欢 emoji 前缀的团队用的预设。3.2 commitlint 配置在项目根目录新建commitlint.config.jsmodule.exports { extends: [commitlint/config-conventional], rules: { type-enum: [ 2, always, [feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert] ], subject-case: [0], header-max-length: [2, always, 100] } };type-enum就是允许的提交类型白名单。subject-case关掉是因为中文提交信息经常被这条规则误伤。header-max-length限制标题长度避免有人写一整段话。3.3 husky 挂载 commit-msg 钩子初始化 husky 并添加钩子npx husky install npx husky add .husky/commit-msg npx --no-install commitlint --edit $1执行完会在.husky/下生成commit-msg文件。之后每次git commitcommitlint 都会先校验信息格式不合格直接拒绝提交。这一步是整条链路的“守门员”没有它后面的 changeLog 就是无源之水。3.4 standard-version 配置在package.json里加脚本同时新建.versionrc文件控制生成行为。package.json的scripts部分{ scripts: { changelog: conventional-changelog -p angular -i CHANGELOG.md -s, changelog:all: conventional-changelog -p angular -i CHANGELOG.md -s -r 0, release: standard-version, release:gitmoji: standard-version --preset gitmoji-config -i CHANGELOG.md --header # 更新日志 } }.versionrc配置{ types: [ { type: feat, section: 新功能 }, { type: fix, section: 问题修复 }, { type: perf, section: 性能优化 }, { type: refactor, section: 代码重构 }, { type: docs, section: 文档更新 }, { type: style, section: 代码格式 }, { type: test, section: 测试相关 }, { type: build, section: 构建依赖 }, { type: ci, section: 持续集成 }, { type: chore, section: 其他改动 }, { type: revert, section: 版本回滚 } ], releaseCommitMessageFormat: chore(release): 发布 v{{currentTag}} }types决定了 CHANGELOG 里每个区块的中文标题。releaseCommitMessageFormat是standard-version自动提交时的信息模板{{currentTag}}会被替换成新版本号。注意conventional-changelog -p angular只会识别fix、feat、perf这几类提交其他类型默认不写入日志。如果你想让refactor、docs也出现在 CHANGELOG 里需要用.versionrc配合standard-version或者自定义 preset。4. 验证请求从一次提交到生成 CHANGELOG.md配置写完必须跑一遍完整链路否则你永远不知道是配置错了还是提交格式错了。4.1 先做一次规范提交改一个文件然后按规范提交git add . git commit -m feat: 新增用户登录页表单校验如果 commitlint 配置生效这条提交会通过。故意写一条不合规的试试git commit -m update login你会看到类似subject may not be empty或type must be one of [...]的报错提交被拒绝。这说明守门员在工作。4.2 生成 CHANGELOG先跑一次只追加最新内容的命令npm run changelog打开CHANGELOG.md应该能看到类似结构### Features * 新增用户登录页表单校验 ### Bug Fixes * 修复列表分页参数丢失问题如果想把历史所有提交都生成一遍用npm run changelog:all-r 0表示从第一个版本开始重新生成适合第一次接入时补全历史记录。4.3 用 standard-version 一键发布确认 CHANGELOG 内容没问题后执行npm run release这条命令会做四件事根据提交类型自动决定版本号feat升 minorfix升 patch、更新package.json版本、生成/更新CHANGELOG.md、创建一个 release commit 并打上 git tag。如果团队用 emoji 前缀改用npm run release:gitmoji它会用gitmoji-config预设解析带 emoji 的提交并自动把# 更新日志作为文件头。4.4 验证结果git log --oneline -3 git tag cat CHANGELOG.md你应该能看到新的 tag比如v1.1.0、release commit以及 CHANGELOG 里新增的区块。到这一步整条链路就算跑通了。5. 本篇常见错排查5.1 提交了但 CHANGELOG 没内容最常见的原因就一个提交信息不符合规范。conventional-changelog只认type: subject这种格式fix : bug修改里冒号前有空格、emoji 在 type 后面都会导致解析失败。正确写法是fix: 修复登录态丢失emoji 可以放在 subject 里但不要放在 type 和冒号之间。另一个原因是只生成了fix、feat、perf。如果你提交的是docs或chore默认不会出现在日志里。解决办法是用standard-version配合.versionrc它会把所有配置的类型都写进去。5.2 commitlint 报错但不知道哪条规则把报错信息完整看一遍通常会指出具体规则名。比如type-enum就是类型不在白名单subject-empty就是冒号后面没写内容。临时想跳过校验可以用git commit --no-verify但只建议在紧急修复时用别养成习惯。5.3 standard-version 版本号不符合预期版本号由提交类型决定有feat升 minor只有fix升 patch有BREAKING CHANGE升 major。如果生成的版本号不对先检查最近一次 tag 到现在的提交里有没有feat。另外如果本地 tag 和远程不一致standard-version可能算错基线先git fetch --tags同步一下。5.4 emoji 提交无法识别conventional-changelog默认不识别 emoji 开头的提交。两个方案一是提交时把 emoji 去掉只保留type: subject二是用conventional-changelog-gitmoji-config预设它专门处理feat: xxx这种格式。VS Code 插件生成的提交如果带 emoji记得在设置里关掉 emoji 展示或者改用 gitmoji 预设。5.5 husky 钩子不生效检查.husky/commit-msg文件是否有执行权限以及package.json里有没有prepare: husky install。如果是新克隆的项目先跑一次npm install触发 prepare再手动npx husky install。6. 把模型能力接进你的发布流程配置跑通之后日常发版就是npm run release一条命令。但团队里总有人提交信息写不规范或者你想让模型帮忙把一堆零散提交归纳成一段人话版的 release note这时候可以接 TaoToken 的 API。具体做法是在项目里加一个脚本读取git log最近一段提交调用模型接口生成摘要再追加到 CHANGELOG 顶部。API 地址用https://taotoken.net/apiKey 在控制台的 API Keys 页面创建。如果你只是偶尔用模型对话页面就够如果要把这个动作固化到 CI 里Coding Plan 更适合长期跑。接入文档里有完整的请求示例和参数说明照着改一下model和messages就能用。这样你的 changeLog 就不只是提交记录的堆砌而是带归纳、带上下文的发布说明。整条链路从 commit 规范开始到自动生成结束中间不需要人工回忆任何东西。