在写新项目的第一天，创建完工程后突然想到：“我该怎么写 commit 信息？”
于是询问 ChatGPT，遂学此规范。
这篇文章记录我对Conventional Commits（约定式提交规范）的理解与使用。
一、Conventional Commits 是什么？
Conventional Commits（约定式提交规范） 脱胎于 Angular 提交信息准则，是一种更通用、更简洁、更灵活的提交信息格式。
它的目标是让提交记录具备结构化语义，便于：
- 自动生成 CHANGELOG；
- 自动管理版本号（符合语义化版本 SemVer）；
- 提高代码审查和协作效率。
二、基本格式
<类型>[可选的作用域]: <描述>
# 空一行
[可选的正文]
# 空一行
[可选的脚注]
示例：
feat(user): add login and register API
add basic authentication support with JWT.
include user registration and login endpoints.
三、type（类型）
| 类型 | 说明 |
|---|---|
| feat | 新功能（feature） |
| fix | 修复 bug |
| docs | 文档相关变更 |
| style | 不影响逻辑的代码格式修改（空格、分号等） |
| refactor | 重构（既不是修复 bug 也不是新增功能） |
| perf | 性能优化 |
| test | 新增或修改测试 |
| chore | 构建过程或辅助工具变动（比如修改依赖、配置） |
| revert | 回滚到上一个版本 |
| merge | 代码合并（通常由 Git 自动生成） |
| sync | 同步主线或分支的改动 |
| to | 特殊用法，表示阶段性修复（中间提交，最终使用 fix 完成） |
💡 建议个人项目以
feat、fix、refactor、chore、docs为主，保持简洁统一。
四、scope（作用域）
scope 用于说明 commit 影响的范围，例如：
feat(user): add login APIfix(order): correct total price calculationrefactor(core): optimize Redis cache logic
具体取决于项目结构。
在多模块项目中（例如 DDD 架构），可使用领域名作为 scope：
feat(order-domain): add order aggregate root
五、subject（简短描述）
- 简短扼要地说明变更目的；
- 不超过 50 个字符；
- 使用祈使语气（即描述动作而非结果）；
- 不加句号或多余标点。
✅ 推荐：
fix: handle null pointer in payment service
🚫 不推荐：
fixed the null pointer bug.
六、正文与脚注（可选）
正文通常解释为什么要这样改、影响范围或实现思路。
脚注可以写上特别标识，例如 BREAKING CHANGE 或 ISSUE 链接。
示例：
feat(auth): add OAuth2 login support
implement OAuth2 authorization code flow for login.
this will replace old JWT-based login.
BREAKING CHANGE: old `/login` endpoint removed.
七、常用模板
# 新功能
feat(<模块>): <简短描述>
# 修复 bug
fix(<模块>): <简短描述>
# 代码重构
refactor(<模块>): <简短描述>
# 文档或注释修改
docs: <简短描述>
# 杂项配置修改
chore: <简短描述>
例如：
chore(init): initialize project structure
八、实际使用建议
- 保持一致性：团队内部要统一格式，避免混乱。
- 粒度适中：一次 commit 做一件清晰的事。
- 配合工具：可以使用
Commitizen、cz-conventional-changelog或 IDE 插件来规范输入。 - 自动化发布：搭配
semantic-release自动生成版本与 CHANGELOG。
九、总结
- 约定式提交让 Git 历史“可读、可分析、可自动化”；
- 即使是个人项目，也值得遵守；
- 养成好习惯，从
init提交开始。
初始化提交建议：
chore(init): initialize project structure
评论