良好的提交规范可以:
约定式提交
- 帮助他人快速理解修改内容;
- 方便代码回滚、审查(Code Review);
- 提高自动化工具(如 CI/CD、Changelog 生成)的准确性;
- 让项目历史清晰可追踪。
约定式提交
目前最常用的标准是 Conventional Commits(约定式提交)。
其基本格式如下:
<type>(<scope>): <subject>
- type:这次提交的类型(做了什么事)
- scope(可选):影响的作用域/模块
- subject:一句话的变更摘要(祈使句,≤ 72 字符为佳)
实例:
feat(login): 新增用户登录功能
fix(api): 修复用户接口超时问题
docs(readme): 更新使用说明文档
type(类型)
说明本次提交的目的,一般包括:
| type | 说明 | 典型示例 |
|---|---|---|
| feat | 新功能(feature) | feat(auth): 支持短信登录 |
| fix | 修 bug | fix(api): 修复分页参数缺失导致 500 |
| docs | 文档相关 | docs(readme): 增加快速开始 |
| style | 代码风格(不改逻辑) | style(ui): 调整卡片边距与排版 |
| refactor | 重构(非新功能/修复) | refactor(core): 抽离缓存层 |
| perf | 性能优化 | perf(list): 减少无效渲染 |
| test | 测试相关 | test(utils): 覆盖边界用例 |
| build | 构建/发布/依赖 | build: 升级 Vite 到 6.x |
| ci | CI/CD 配置 | ci: 拆分测试与构建流水线 |
| chore | 杂项(开发辅助、脚手架) | chore: 调整 lint-staged 规则 |
| revert | 回滚 | revert: "feat(auth): 支持短信登录" |
BREAKING CHANGE:(见下文)scope(范围)
可选项,表示影响的模块或文件,如:
feat(auth): 新增 token 验证逻辑
fix(ui): 修复按钮样式问题
subject(主题)
一句简短的描述,不超过 50 个字符。
- 用祈使语气:用“增加”而不是“增加了”;
- 不用句号结尾。
feat: 支持暗黑模式切换
扩展内容(可选)
可选的正文与页脚用于补充说明与关联合并请求/问题单:
<type>(<scope>): <subject>
<body>
<footer>
- body:详细描述更改的原因、思路或影响;
- footer:关联 issue 或破坏性更新说明(如
BREAKING CHANGE)。
feat(api): 新增数据同步接口
新增 /sync/data 接口用于前端同步本地缓存。
BREAKING CHANGE: 删除旧版 /data/update 接口。
进阶:语义化版本(SemVer)配合使用
约定式提交通常和语义化版本(Semantic Versioning)结合使用:
fix:⇒ 触发 补丁号(patch)升级,如1.0.0 → 1.0.1feat:⇒ 触发 次版本号(minor)升级,如1.0.0 → 1.1.0- 提交中包含
BREAKING CHANGE:⇒ 触发 主版本号(major)升级,如1.0.0 → 2.0.0
feat(api): 添加新接口
BREAKING CHANGE: 原有 /v1 接口被移除
