彻底搞懂 Conventional Commits：规范你的 Git 提交日志

在日常开发中，绝大多数人写 Git 提交日志都很随意：update code、修复bug、调整样式。短期看似省事，等到需要排查问题、回溯代码、生成版本日志、梳理迭代内容时，混乱的 commit 记录会让所有人陷入崩溃。

而 Conventional Commits（约定式提交） 就是为解决这个问题而生的轻量级 Git 提交规范，目前已是开源项目、企业团队的主流提交标准，搭配语义化版本、自动化 CHANGELOG、代码评审，能极大提升团队协作效率。今天就带大家从零吃透这套规范，直接落地到日常开发。

一、什么是 Conventional Commits？

Conventional Commits 是一套基于提交信息的轻量级约定规范，核心是让 Git commit 信息具备结构化、可读性、可机器识别性。所有提交记录都遵循统一格式，无需人工整理，就能清晰区分新增功能、Bug 修复、代码重构、文档修改等变更类型。

这套规范最大的价值是和 SemVer（语义化版本） 深度绑定，能够自动化生成版本号、更新 CHANGELOG 文档，完美适配现代化 CI/CD 工作流，也是主流开源项目的强制提交标准。

二、标准提交格式（核心必记）

一份合规的 Conventional Commits 提交信息分为 Header（必填）、Body（可选）、Footer（可选） 三部分，整体结构固定，简洁易记：

<type>[可选 scope]: <简短描述>

[可选 详细正文，描述变更原因与细节]

[可选 尾部备注，关联任务、标记破坏性变更]

1. Header 头部（必填，最核心）

Header 是每一次 commit 的核心标识，也是日常开发最常编写的部分，由三部分组成：type + scope（可选） + description。

（1）type：变更类型（核心分类）

用于定义本次提交的代码变更类型，是规范的核心，所有类型都有明确用途，不可随意填写，主流类型如下：

• feat：新增功能（对应 SemVer 次版本号 MINOR 升级），比如新增登录、列表筛选、支付功能等用户可见新能力

• fix：修复 Bug（对应 SemVer 修订号 PATCH 升级），解决线上、测试环境的功能异常、逻辑错误问题

• docs：仅文档变更，不修改业务代码，比如更新接口文档、README、注释说明

• style：代码格式调整，不影响代码逻辑与功能，比如缩进、空格、分号、代码格式化

• refactor：代码重构，既不新增功能，也不修复 Bug，仅优化代码结构、简化逻辑、去除冗余

• perf：性能优化，提升程序运行效率、加载速度、内存占用等

• test：测试相关变更，新增测试用例、修改单元测试、修复测试代码问题

• build：构建系统、依赖变更，修改打包配置、更新第三方依赖、调整构建脚本

• ci：持续集成配置变更，修改 Jenkins、GitHub Actions、GitLab CI 等自动化部署配置

• chore：杂项变更，不属于以上类型的琐碎修改，比如更新忽略文件、调整项目目录、修改工具配置

• revert：回滚某次提交，撤销之前的代码变更

（2）scope：影响范围（可选）

用于精准标注本次变更影响的模块、页面、功能、文件，让提交记录更清晰，无固定规则，团队可自定义。常见示例：login、user、api、ui、order、config。

示例：feat\(login\): 新增手机号验证码登录

（3）description：简短描述（必填）

用一句话简洁描述本次变更内容，遵循三个原则：现在时态、祈使语气、无句号结尾，语言通俗易懂，避免模糊描述。

✅ 正确示例：fix: 修复列表分页数据重复问题

❌ 错误示例：修复了列表分页的bug。（过去式、带句号）、改了点东西（描述模糊）

2. Body 正文（可选）

用于详细补充变更细节，适合复杂变更场景。可以说明为什么修改、修改逻辑、解决了什么问题、带来的影响，普通简单提交可省略。正文需要和 Header 之间空一行。

3. Footer 尾部（可选）

用于标注特殊信息，常用场景有两种：

1. 破坏性变更：使用 BREAKING CHANGE: 开头，标注不兼容变更，对应 SemVer 主版本号 MAJOR 升级

2. 关联任务：关联需求、Bug 工单、Issue，比如 fix \#123、close \#456

三、规范提交实战示例（直接抄作业）

这里整理了日常开发高频场景的标准提交示例，覆盖绝大多数业务需求：

1. 基础简单提交（日常最常用）

# 新增功能
feat(user): 新增用户头像上传功能

# 修复bug
fix(order): 修复订单提交重复请求问题

# 文档更新
docs: 更新项目本地启动文档

# 代码格式化
style: 统一代码缩进格式

# 代码重构
refactor(api): 重构用户接口请求逻辑

# 性能优化
perf(list): 优化长列表渲染卡顿问题

# 新增测试用例
test(login): 新增登录接口单元测试

# 依赖更新
build: 升级axios至最新稳定版本

# CI配置修改
ci: 调整自动化打包分支规则

# 杂项配置修改
chore: 更新gitignore忽略文件

2. 完整详细提交（复杂变更）

feat(pay): 新增微信支付结算功能

对接微信支付官方结算接口，支持订单自动结算、对账回调，优化结算时效

close #208

3. 破坏性变更提交（版本大版本升级）

feat(user): 重构用户信息存储结构

调整用户数据表字段规则，废弃旧版用户信息接口，适配新的数据架构

BREAKING CHANGE: 旧版/user/info接口不再兼容，需适配新接口地址
close #195

4. 回滚提交

revert: 回滚新增购物车满减功能

该功能存在结算逻辑漏洞，暂时撤回迭代，后续优化后重新上线

四、为什么必须遵守这套规范？

很多同学觉得规范繁琐、浪费时间，但长期来看，规范提交的收益远超成本：

1. 清晰的代码提交历史，便于问题回溯

混乱的 commit 日志无法快速定位问题，规范后的提交可以通过类型、模块、描述，快速找到对应变更记录，排查 Bug、代码复盘效率大幅提升。

2. 自动化生成版本与更新日志

配合 standard\-version、semantic\-release 等工具，可根据 commit 记录自动升级版本号、生成 CHANGELOG.md，无需人工手动整理，适配自动化发布流程。

3. 统一团队编码协作标准

避免团队成员提交风格参差不齐，新人上手即可遵循统一规范，降低沟通成本，提升代码评审、迭代复盘效率。

4. 精准区分版本变更级别

自动区分 feat（小版本迭代）、fix（补丁修复）、BREAKING CHANGE（大版本迭代），完美适配语义化版本管理，让版本迭代更规范可控。

五、落地工具推荐（告别手动记规范）

不用死记硬背格式，借助工具可一键生成规范 commit，还能强制校验，杜绝不规范提交：

• Commitlint + Husky：前端/全栈项目主流方案，提交代码时自动校验 commit 格式，不规范则禁止提交，强制落地规范

• cz-git / commitizen：交互式提交工具，命令行选择变更类型、填写描述，自动生成合规 commit 信息

• VS Code 插件：Conventional Commits 插件，编辑器内一键生成规范提交模板

六、常见误区避坑

• 不要滥用 chore：只有不属于 feat/fix/docs 等明确类型的变更才使用，不要所有杂项修改都无脑用 chore

• 描述拒绝模糊：禁止 更新代码、优化代码 等无效描述，必须精准说明变更内容

• 区分 refactor 和 perf：重构是优化代码结构，无体验/性能提升；性能优化是明确提升运行效率，二者不可混用

• 区分 style 和 refactor：仅格式调整用 style，修改代码逻辑结构用 refactor

七、总结

Conventional Commits 不是繁琐的条条框框，而是提升团队协作效率、标准化迭代流程的基础工具。看似每次提交多花几十秒规范格式，却能在问题排查、版本管理、迭代复盘、自动化部署等场景节省大量时间。

无论是个人项目规范沉淀，还是企业团队统一协作标准，这套规范都是最优选择。建议所有开发者养成规范提交习惯，搭配工具自动校验，彻底告别杂乱的 Git 提交日志。

（注：文档部分内容可能由 AI 生成）