18-迭代日志自动化生成：CHANGELOG自动更新、版本内容追溯
前言
大家好，我是黒漂技术佬。
你有没有遇到过这种场景：版本上线了，产品经理问"这次更新了啥？“你翻了半天 Git 提交记录，东拼西凑凑出一个发布说明。更惨的是，三个月后老板问"v2.3 版本改了哪些东西？”——你得重新翻 Git 历史，那叫一个痛苦。
今天咱们就来解决这个痛点：如何让 CHANGELOG 自动生成，告别手工整理。
一、为什么需要自动化 CHANGELOG？
先看一个"手工版" CHANGELOG 是什么样：
v2.3.1 更新内容： - 修复了一些 Bug - 优化了部分功能 - 调整了几个页面这种 CHANGELOG 等于没写。真正的变更日志应该是：
## v2.3.1 (2024-06-15) ### Bug Fixes - **锁控模块**: 修复SPI通信超时导致出货失败的问题 (#4782) - **支付模块**: 修复网络断开后重复扣款的问题 (#4756) ### Features - **扫码模块**: 新增低光照环境下自动补光功能 (#4701) - **后台管理**: 新增设备在线率实时统计面板 (#4710)每一步改动都有据可查、可追溯。工具化是实现这种日志的唯一出路。
二、Conventional Commits：自动化日志的前提
想让工具自动生成 CHANGELOG，前提是你的 Commit Message 遵循规范。这就是Conventional Commits（约定式提交）：
<type>(<scope>): <subject> [optional body] [optional footer]常用 type 对照表：
| Type | 说明 | CHANGELOG 归类 |
|---|---|---|
feat | 新功能 | Features |
fix | Bug 修复 | Bug Fixes |
docs | 文档更新 | 不出现 |
style | 代码格式（不影响逻辑） | 不出现 |
refactor | 重构 | 不出现 |
perf | 性能优化 | Performance Improvements |
test | 测试相关 | 不出现 |
chore | 构建/工具配置 | 不出现 |
BREAKING CHANGE | 不兼容变更 | BREAKING CHANGES |
示例：
gitcommit-m"feat(lock): 增加USB转串口驱动的热插拔检测 设备端插入USB转串口模块后，无需重启即可自动识别并初始化。 采用udev规则监听设备事件，驱动层自动绑定。 Closes #4892"这样工具就能自动把这条 commit 归到版本日志的Features分类下。
三、实战：用 standard-version 一键生成 CHANGELOG
standard-version是目前最主流的自动化版本管理和 CHANGELOG 生成工具。
3.1 安装与配置
# 项目根目录安装npminstall--save-dev standard-version在package.json中添加脚本：
{"scripts":{"release":"standard-version","release:minor":"standard-version --release-as minor","release:patch":"standard-version --release-as patch"}}3.2 执行发版
# 自动根据 Commit 类型决定版本号升级# feat → minor, fix → patch, BREAKING CHANGE → majornpmrun release# 指定版本号npmrun release:patch# v2.3.0 → v2.3.1npmrun release:minor# v2.3.0 → v2.4.0执行后，standard-version会自动做三件事：
- 升级版本号：更新
package.json中的 version 字段 - 生成 CHANGELOG：在
CHANGELOG.md中追加新的版本日志 - 创建 Git Tag：自动
git tag v2.3.1
生成的CHANGELOG.md大概长这样：
# Changelog ## [2.3.1](https://git.example.com/compare/v2.3.0...v2.3.1) (2024-06-15) ### Bug Fixes * **lock**: 修复SPI通信超时导致出货失败 ([abc1234](https://git.example.com/commit/abc1234)) * **payment**: 修复重复扣款问题 ([def5678](https://git.example.com/commit/def5678)) ### Features * **scan**: 新增低光照自动补光功能 ([ghi9012](https://git.example.com/commit/ghi9012))3.3 多个仓库怎么办？
我们团队有 3 个仓库：后端微服务、安卓固件、小程序。如果都用 npm 项目，每个仓库单独配置即可。对于非 npm 项目（比如 Android 固件、纯 Python 项目），可以用conventional-changelog直接生成：
# 不修改package.json，只生成CHANGELOGnpx conventional-changelog-pangular-iCHANGELOG.md-s-r0四、CI/CD 集成：自动更新 CHANGELOG
更进一步，我们可以把 CHANGELOG 生成集成到 CI/CD 流程中，每次合并到 master 自动触发。
.gitlab-ci.yml 示例：
release:stage:releaseonly:-masterscript:-npm ci-git config user.email "ci-bot@example.com"-git config user.name "CI Bot"-npm run release-git push--follow-tags origin master这样每次合并到 master，CI 会自动：
- 扫描所有 commit 类型
- 确定版本号升级方式
- 生成/更新 CHANGELOG.md
- 打 Tag 并推送
五、版本内容追溯：从"猜"到"查"
自动化 CHANGELOG 最大的价值不是"看起来好看"，而是可追溯。
有了规范化的 CHANGELOG，你可以：
- 快速回顾：
git log v2.3.0..v2.3.1 --oneline一秒定位改动范围 - 关联 Issue：每条改动都链接到对应的 Issue/Task，形成需求→开发→发布的闭环
- 审计合规：客户或监管要求提供"某版本改了什么"，直接发 CHANGELOG 就行
- 季度复盘：一看 CHANGELOG 就知道这个季度产出了多少 Feature、修了多少 Bug
# 一键查看两个版本之间的所有变更gitlog v2.3.0..v2.3.1--oneline--no-merges六、常见坑与最佳实践
- Commit 不规范，日志就废了——在团队推 Conventional Commits 之前，先用
commitlint+ Husky 做提交校验，不合规的 commit 直接拒绝 - 不要手动改 CHANGELOG——手动改了下次自动生成会冲突，让工具全权管理
- release commit 也要规范——
standard-version生成的 commit 默认是chore(release): 2.3.1，不要手动去改它 - 多仓库统一规范——后端 Java 项目、前端小程序、固件 C++ 项目都要遵守相同的 Commit 规范
commitlint 配置示例（commitlint.config.js）：
module.exports={extends:['@commitlint/config-conventional'],rules:{'type-enum':[2,'always',['feat','fix','docs','style','refactor','perf','test','chore','revert','build','ci']],'subject-max-length':[2,'always',72]}};总结
自动化 CHANGELOG 的核心逻辑很简单：规范 Commit → 工具解析 → 自动生成。前期投入一点时间规范团队的提交习惯，换来的是永久告别手工整理日志的痛苦。
记住一句话：**你写的每一条 Commit Message，都是写给三个月后的自己看的。**既然要写，就写得规范一点。
