Git 提交信息规范

这是一份面向日常开发的 Git 提交信息规范，采用 Conventional Commits 格式，并使用中文描述具体变更。统一格式有助于检索历史、审查改动和生成发布说明。

快速索引

变更场景	推荐格式
新增功能	`feat(module): 增加某项功能`
修复缺陷	`fix(module): 修复某个问题`
更新文档	`docs: 更新使用说明`
调整内部实现	`refactor(module): 重构某段逻辑`
优化性能	`perf(module): 减少重复查询`
增加测试	`test(module): 补充边界测试`
破坏性变更	`feat(api)!: 调整响应结构`
回滚提交	`revert: 回滚某项变更`

标准格式

完整结构

<type>[可选作用域][!]: <简短描述>

[可选正文]

[可选脚注]

日常提交通常只需要标题：

<type>[可选作用域]: <简短描述>

例如：

feat(auth): 增加手机号登录
fix(order): 修复重复提交订单的问题
docs: 更新本地启动说明

标题要求

type 必填，用于说明变更类别。
scope 可选，用于说明受影响的模块。
! 可选，用于标识破坏性变更。
冒号后保留一个半角空格，再填写简短描述。
标题应完整表达一个目的，避免堆叠互不相关的改动。

提交类型

类型	适用场景	默认语义版本影响	示例
`feat`	新增功能或新特性	Minor：`x.Y.z`	`feat: 增加文件上传功能`
`fix`	修复 Bug 或缺陷	Patch：`x.y.Z`	`fix: 修复分页数据错乱`
`docs`	仅修改文档	不升级	`docs: 更新安装说明`
`refactor`	不增加功能、不修复缺陷的代码重构	不升级	`refactor: 抽离用户校验逻辑`
`perf`	性能优化	Patch：`x.y.Z`	`perf: 减少列表查询次数`
`test`	新增或修改测试	不升级	`test: 补充登录接口单元测试`
`style`	不影响逻辑的代码格式调整	不升级	`style: 统一缩进格式`
`build`	构建系统、打包配置或依赖变更	不升级	`build: 调整生产环境构建参数`
`ci`	持续集成配置或脚本变更	不升级	`ci: 增加文档构建检查`
`chore`	其他不影响产品行为的工程维护	不升级	`chore: 清理无用脚本`
`revert`	回滚之前的提交	取决于回滚内容	`revert: 回滚文件上传功能`

语义版本不会自动变化

上表描述的是常见映射约定。只有项目接入 semantic-release 等自动发布工具并完成相应配置后，提交类型才会自动影响版本号。

容易混淆的类型

情况	应使用	原因
修复用户可见的错误	`fix`	产品行为由错误恢复为预期结果
只整理代码且行为不变	`refactor`	没有增加功能或修复缺陷
只调整空格、换行或格式	`style`	不影响代码运行逻辑
升级运行时依赖	`build`	可能影响构建或运行产物
清理本地开发脚本	`chore`	属于工程维护，不影响产品行为

作用域

命名原则

作用域用于说明变更所属的模块、页面或接口，应简短、稳定并使用项目内统一的英文名称：

feat(auth): 增加短信验证码登录
fix(cart): 修复购物车金额计算错误
docs(api): 补充订单接口示例

同一项目应维护统一的作用域命名，避免对同一模块交替使用 user、users 和 member 等不同名称。跨越多个模块且无法准确归类时，可以省略作用域。

作用域不是文件名

作用域应表达稳定的业务或系统边界，而不是某次修改涉及的具体文件。文件重命名后，历史提交仍应便于检索。

简短描述

编写要求

准确说明本次提交完成了什么。
使用明确的动词，例如“增加”“修复”“移除”“调整”。
避免使用“修改代码”“更新内容”“处理问题”等缺少上下文的描述。
一次提交只表达一个完整目的。
不写密钥、令牌、密码、真实用户数据等敏感信息。

推荐不推荐

fix(order): 防止支付回调重复创建流水

fix: 修改问题
update
feat: 增加登录并重构订单和更新文档

正文与脚注

补充变更背景

当变更原因、约束或迁移方式无法在标题中说明时，应补充正文：

fix(order): 防止支付回调重复处理

支付平台可能重复发送同一回调。本次变更以交易号作为幂等键，
避免重复更新订单状态和重复写入支付流水。

Refs: #128

正文重点说明为什么修改、行为如何变化，以及是否存在兼容性或部署注意事项。标题与正文之间、正文与脚注之间各保留一个空行。

关联任务或问题

常用脚注示例：

Refs: #128
Closes: #256
Co-authored-by: Your Name <your-email@example.com>

Refs 表示关联问题，Closes 表示合并后关闭问题。具体关键字是否生效取决于代码托管平台的规则。

破坏性变更

标记方式

存在不兼容的 API、配置或数据格式变化时，在类型或作用域后添加 !，并在脚注中说明影响和迁移方式：

feat(api)!: 调整用户查询接口响应结构

BREAKING CHANGE: `data.list` 已改为 `data.items`，调用方需要同步更新字段读取逻辑。

破坏性变更通常对应 Major 版本升级：X.y.z。

必须提供迁移说明

仅添加 ! 不能让调用方理解如何升级。脚注应说明受影响范围、旧行为、新行为和必要的迁移步骤。

特殊提交

回滚提交

使用 git revert 回滚已经共享的提交时，应说明被回滚的内容和原因：

revert: 回滚文件上传功能

上传接口在大文件场景下出现资源耗尽，暂时回滚以恢复服务稳定性。

Reverts: <commit>

相关命令和安全注意事项参见 Git 常用命令指南。

合并提交

由代码托管平台自动生成的合并提交可以保留平台格式。手动合并时，提交信息应说明合并来源和目的，避免只写 merge。

提交拆分

一个提交应保持逻辑完整且可以独立审查。以下改动通常应拆分提交：

功能实现与无关代码格式化。
缺陷修复与不相关的依赖升级。
可独立验证的多个功能。
大范围机械修改与业务逻辑调整。

如果测试或文档只服务于当前功能，应与功能代码放在同一提交中，确保该提交本身完整可验证。

创建提交

检查并提交

# 查看工作区状态
git status -sb

# 检查尚未暂存的改动
git diff

# 按代码片段选择要暂存的内容
git add -p

# 检查即将提交的内容
git diff --staged

# 创建提交
git commit -m "feat(module): 增加某项功能"

需要填写正文或脚注时，直接执行 git commit，在编辑器中按标准格式编写完整信息。

提交前核对暂存区

git commit 只提交暂存区内容。执行前使用 git diff --staged，避免遗漏必要文件或混入调试代码、生成物和敏感信息。

提交前检查

提交只包含一个清晰、完整的变更目的。
提交类型与实际变更一致。
作用域明确且使用项目统一命名。
描述能够脱离当前上下文独立说明变更目的。
破坏性变更包含影响范围和迁移说明。
提交中没有调试文件、意外生成物或敏感信息。
相关测试已经执行，文档、配置示例和迁移说明已同步更新。

完整的暂存、提交和撤销操作参见 Git 常用命令指南。