约定式提交完全指南:让 Commit 历史替你干活

打开一个老项目的 git log,前十条提交里有「修改了一些东西」「fix bug」「update」「再改一下」。这种历史能查到什么?查不到。半年后想知道某个版本动了哪些功能,只能一条条点开 diff 看。约定式提交(Conventional Commits)就是为了根治这种混乱:它给提交信息的第一行定了一条简单规则,让机器和人都能一眼读懂每条提交的意图。

约定式提交的三段式格式

核心格式只有一行:

type(scope): description

拆开看是三部分。type 说明这是哪类改动,常用的有 feat(新功能)、fix(修复)、docs(文档)、style(格式)、refactor(重构)、perf(性能)、test(测试)、build(构建)、ci(持续集成)、chore(杂务)、revert(回滚)。scope 是括号里一个可选的名词,标出这次改动碰到的代码部位,比如 (api)、(auth)、(ui)。description 是一句小写、祈使语气的简短摘要,末尾不加句号。

一个真实例子:

feat(auth): 添加登录功能

或者按很多团队习惯的英文写法:

feat(auth): add passkey login support

头部之外还有可选的正文和脚注,跟在空一行之后。正文写清「为什么这么改」,脚注用来关联 issue,比如 Closes #214,合并时 GitHub 会自动关掉那个工单。

为什么值得用:changelog 和版本号自动化

很多人觉得约定式提交是给人看的,其实最大的价值是给机器看。结构化的提交让工具替你做以前靠手工做的事。

像 semantic-release 这样的工具会读你的标记来决定下一个版本号:feat 读成 MINOR 升级(1.4.0 到 1.5.0),fix 读成 PATCH 升级(1.4.0 到 1.4.1),带 BREAKING CHANGE 的改动强制 MAJOR 升级(1.4.0 到 2.0.0)。它打好 tag,再按类型分组写出整份 changelog,Features 一栏、Bug Fixes 一栏,清清楚楚。如果你想手动确认某次发布该升到哪个版本号,可以用 /zh/t/semver-increment/ 对照着算一遍,语义和工具读出来的结果应该一致。

就算你完全不上自动化,收益也在。审查者扫一眼 git log 看到 fix(parser): handle empty input,一眼就懂意图,不用去猜那种随手写的自由格式信息。

破坏性变更怎么标

破坏性变更要标两处,缺一不可。第一处在头部冒号前面加一个 !:

feat(api)!: drop v1 endpoints

第二处加一行以 BREAKING CHANGE: 开头的脚注,写清什么坏了、怎么迁移:

BREAKING CHANGE: 改用 v2 路由,迁移说明见 docs/migration.md

只用 ! 而跳过脚注是个常见坑。! 只是提示,真正触发大版本升级的是 BREAKING CHANGE 脚注那一行。两处都写好,发布流水线才会自动切一个 MAJOR 版本并提醒下游使用方。

feat 和 fix 别搞混

这两个最容易混。feat 表示新增了以前没有的能力,比如 feat(auth): add passkey login。fix 表示修正了本来就该正常工作的行为,比如 fix(auth): reject expired tokens。区别之所以重要,是因为它直接决定版本号怎么跳。既不算新功能也不算用户可见修复的改动,该用 chore、docs、refactor 或 test,别一律塞进 fix。

团队协作:让规范自己长出来

我自己带前端组的时候试过推这套规范,一开始最大的阻力不是技术,是「记不住有哪些 type」。后来发现根本不用让谁去背。把生成器链接发到群里,新同事点开就是类型下拉菜单摆在那:选 fix,看到 scope 和描述字段,要是把描述首字母写大了或者末尾加了句号,立刻收到提示。一周下来,整个组的提交格式就收敛到了一种,谁也没专门去学规范文档。

这就是 约定式提交生成器 想解决的事:选类型、填范围、写一句摘要,它边填边按规范拼好头部、正文和脚注,头部、正文、脚注之间留一个空行,正好是 semantic-release、changelog 生成器这类解析工具预期的格式。校验会实时提示描述过长、末尾带句号、首字母大写这些问题,拼好一键复制粘进 git commit 就行。全部在浏览器本地跑,不上传任何内容。

几条落地建议

• scope 写短、写统一,团队复用同一套词;改动真的覆盖全项目时就留空。
• 整个头部控制在约 72 个字符以内,这样在 GitHub、git log --oneline 和终端里都能一行读完,多余细节放进正文。
• 描述用祈使语气:写 add、fix、remove,不要写 added 或 fixes。
• 类型后面的冒号加恰好一个空格,挤在一起会让所有解析器报错。

规范本身很轻,真正难的是坚持。把校验交给工具、把记忆负担降到零,坚持就不再靠自觉。等你第一次看着 changelog 自动生成、版本号自动跳对,就再也回不去手写「update」的日子了。

---

Made by Toolora · Updated 2026-06-13