Git 约定式提交（Conventional Commits）规范说明文档
目录
- Git 约定式提交（Conventional Commits）规范说明文档
- 1. 文档目的
- 2. 核心定义
- 3. 规范格式
- 3.1 基础格式
- 3.2 字段说明
- 3.3 示例
- 4. 提交类型（type）全量说明
- 4.1 核心类型（高频使用）
- 4.2 辅助类型（低频使用）
- 5. 作用域（scope）规范
- 5.1 定义
- 5.2 规则
- 6. 最佳实践
- 6.1 提交原则
- 6.2 禁止场景
- 6.3 自动化落地
- 7. 常见问题
- 7.1 如何区分 refactor 和 feat/fix？
- 7.2 破坏性变更如何标注？
- 7.3 团队可自定义类型吗？
- 8. 文档维护
- 总结
你需要的是一份可直接落地使用的Git 约定式提交（Conventional Commits）规范说明文档，我为你整理了一份结构完整、内容详实的标准版文档，涵盖核心定义、规范格式、类型说明、最佳实践等，可直接用于团队协作或项目文档归档。
Git 约定式提交（Conventional Commits）规范说明文档
1. 文档目的
标准化团队代码提交信息的书写格式，实现以下目标：
- 提升提交记录的可读性，便于快速追溯代码变更背景；
- 支持自动化生成 CHANGELOG（版本变更日志）；
- 辅助语义化版本号（Semantic Versioning）的自动管理；
- 统一团队协作规范，降低代码评审和维护成本。
2. 核心定义
约定式提交是一种基于 Git 提交信息的轻量级约定，核心规则：
- 提交信息必须以类型前缀开头，后跟可选的作用域、冒号+空格，最后是简洁的提交描述；
- 提交信息需使用中文/英文（团队统一即可），简洁明了，不超过 72 个字符；
- 提交内容需单一职责，一个提交仅对应一个变更点（如仅修复一个 bug、仅新增一个功能）。
3. 规范格式
3.1 基础格式
<type>(<scope>): <subject> [可选的详细描述] [可选的脚注]3.2 字段说明
| 字段 | 必选/可选 | 说明 |
|---|---|---|
type | 必选 | 提交类型，标识本次提交的核心目的（如 feat、fix、refactor）； |
scope | 可选 | 提交作用域，标识本次提交影响的模块/功能/目录（如 home、user、api）； |
subject | 必选 | 提交简短描述，使用祈使句、现在时（如“新增”而非“新增了”，“修复”而非“修复了”）； |
| 详细描述 | 可选 | 对提交内容的补充说明，适用于复杂变更，换行后书写； |
| 脚注 | 可选 | 用于标注破坏性变更（BREAKING CHANGE）、关联Issue/PR编号等； |
3.3 示例
# 基础示例（仅核心字段） feat(home): 新增首页轮播图功能 # 完整示例（含详细描述+脚注） fix(order): 修复订单支付后状态未同步问题 详细描述： 1. 修复支付回调接口未更新订单状态的逻辑漏洞； 2. 补充订单状态更新的异常捕获机制。 关联Issue: #1234. 提交类型（type）全量说明
4.1 核心类型（高频使用）
| 类型 | 中文名称 | 适用场景 | 示例 |
|---|---|---|---|
feat | 新功能 | 新增产品功能、业务逻辑、接口、页面等（会体现在CHANGELOG中）； | feat(user): 新增用户手机号绑定功能 |
fix | 缺陷修复 | 修复现有功能的bug、逻辑错误、兼容性问题等（会体现在CHANGELOG中）； | fix(trade): 修复结算金额计算错误 |
refactor | 代码重构 | 仅优化代码实现，不新增功能、不修复bug（如逻辑拆分、技术栈升级、写法优化）； | refactor(chart): 重构图表渲染逻辑 |
docs | 文档变更 | 仅修改文档（README、注释、接口文档、帮助文档等），不涉及业务代码； | docs(api): 补充用户接口参数说明 |
style | 格式调整 | 仅调整代码格式（空格、缩进、分号、命名规范），不改变逻辑； | style(common): 统一代码缩进为4个空格 |
perf | 性能优化 | 优化性能（加载速度、渲染效率、接口响应、内存占用等），不改变业务功能； | perf(list): 优化列表大数据渲染性能 |
test | 测试相关 | 新增/修改测试用例、修复测试代码、完善测试覆盖； | test(pay): 新增支付接口单元测试 |
4.2 辅助类型（低频使用）
| 类型 | 中文名称 | 适用场景 | 示例 |
|---|---|---|---|
chore | 工程琐事 | 构建/依赖/配置相关变更（如更新npm包、修改.gitignore、调整工程目录）； | chore(deps): 更新axios至1.6.0版本 |
build | 构建变更 | 构建工具配置修改（webpack/vite/rollup等）； | build(vite): 新增生产环境压缩配置 |
ci | 集成变更 | 持续集成流程修改（GitHub Actions/Jenkins/GitLab CI等）； | ci: 调整CI构建触发规则 |
revert | 版本回滚 | 撤销之前的提交，恢复到历史版本； | revert: feat(home): 新增首页轮播图功能 |
breaking | 破坏性变更 | 变更会导致现有功能不可用（需配合脚注标注 BREAKING CHANGE）； | breaking(api): 重构用户接口入参格式 |
5. 作用域（scope）规范
5.1 定义
标识提交影响的模块/范围，建议按以下维度划分：
- 业务模块：home（首页）、user（用户）、order（订单）、pay（支付）等；
- 技术模块：api（接口）、utils（工具类）、components（组件）、router（路由）等；
- 目录名称：src/views、src/store、src/api 等（适用于小型项目）。
5.2 规则
- 作用域使用小写英文，简洁且团队统一；
- 无明确作用域时可省略，如
docs: 更新README.md。
6. 最佳实践
6.1 提交原则
- 单一职责：一个提交仅做一件事（如“修复一个bug”而非“修复bug+新增功能”）；
- 粒度适中：避免超大提交（如一次性修改10个文件），也避免过细提交（如“修改一个标点”）；
- 描述精准：避免模糊描述（如“修复问题”），需明确具体内容（如“修复登录按钮点击无响应”）。
6.2 禁止场景
- 禁止无意义提交：如“测试”“修改代码”“临时提交”；
- 禁止混用类型：如
feat+fix: 新增功能并修复bug（应拆分为两个提交）； - 禁止超长描述：subject 部分控制在72字符内，复杂说明写在“详细描述”中。
6.3 自动化落地
- 使用
commitlint校验提交信息格式（不符合规范则禁止提交）； - 使用
standard-version/semantic-release自动生成 CHANGELOG 和语义化版本号。
7. 常见问题
7.1 如何区分 refactor 和 feat/fix？
refactor：功能“对外表现”无变化，仅内部实现优化；feat/fix：功能“对外表现”有变化（新增/修复）。
7.2 破坏性变更如何标注？
在提交信息的脚注中添加BREAKING CHANGE: 变更说明，示例：
refactor(api): 重构用户接口 BREAKING CHANGE: 用户列表接口返回字段格式调整，需前端适配7.3 团队可自定义类型吗？
可以，核心类型需保留（feat/fix/refactor），可新增团队专属类型（如config用于配置变更、mock用于模拟数据变更）。
8. 文档维护
- 本规范由团队技术负责人维护；
- 规范变更需同步更新本文档，并通知全体团队成员；
- 新成员入职需学习本规范，确保提交格式统一。
总结
- 约定式提交核心是通过
type(scope): subject格式标准化提交信息，核心类型为feat（新功能）、fix（修复）、refactor（重构）； - 提交需遵循“单一职责”原则，描述精准、粒度适中；
- 规范可结合自动化工具（commitlint/semantic-release）落地，提升团队协作效率。