Git 提交信息规范指南：常用类型与最佳实践

为什么需要规范的提交信息

在团队协作中，规范的 Git 提交信息能够：

快速理解变更内容：无需深入代码就能了解每次提交做了什么
自动生成 Changelog：基于提交类型自动生成版本更新日志
便于版本管理：明确区分功能更新、Bug 修复、破坏性变更等
提高代码审查效率：审查者能快速定位关注重点
支持自动化工具：语义化版本发布、CI/CD 流程等

提交信息的基本格式

标准的提交信息遵循以下结构：

<type>(<scope>): <subject>

<body>

<footer>

格式说明

type（必需）：提交的类型，如 feat、fix 等
scope（可选）：影响的范围，如 auth、api、ui 等
subject（必需）：简短描述，不超过 50 字符
body（可选）：详细描述变更的动机、实现方式等
footer（可选）：关联的 Issue、破坏性变更说明等

基本示例

feat(auth): 添加用户登录功能

实现了基于 JWT 的用户认证系统，包括：
- 登录接口
- Token 验证中间件
- 刷新 Token 机制

Closes #123

常用提交类型（Type）详解

1. `feat` - 新功能

用于添加新功能或特性。

# 简单功能
feat: 添加暗黑模式切换按钮

# 带作用域
feat(payment): 集成支付宝支付接口

# 带详细描述
feat(search): 实现全文搜索功能

新增 Elasticsearch 集成，支持：
- 多字段模糊查询
- 高亮显示匹配结果
- 分页与排序

Closes #456

使用场景：

添加新的用户功能
新增 API 接口
引入新的组件或模块

2. `fix` - 修复 Bug

用于修复缺陷或问题。

# 简单修复
fix: 修复登录页面重复提交问题

# 带作用域
fix(cart): 修复购物车数量计算错误

# 详细说明
fix(api): 修复并发请求导致的数据不一致

问题原因：未对共享资源加锁
解决方案：使用 Redis 分布式锁

Fixes #789

使用场景：

修复用户报告的 Bug
解决代码逻辑错误
修正样式或布局问题

3. `docs` - 文档更新

仅涉及文档的变更。

# 更新 README
docs: 更新安装说明文档

# API 文档
docs(api): 补充用户接口的参数说明

# 注释优化
docs: 为核心模块添加详细注释

使用场景：

修改 README.md
更新 API 文档
完善代码注释

4. `style` - 代码格式

不影响代码逻辑的格式调整（注意：不是 CSS 样式）。

# 格式化代码
style: 格式化代码符合 ESLint 规则

# 移除空白
style: 移除多余的空行和尾随空格

# 统一风格
style(components): 统一使用单引号

使用场景：

代码格式化（Prettier/ESLint）
缩进、空格、换行调整
不改变代码语义的修改

5. `refactor` - 重构

既不修复 Bug 也不添加功能的代码重构。

# 重构函数
refactor: 简化用户验证逻辑

# 提取公共代码
refactor(utils): 将日期处理函数抽取为工具类

# 重构架构
refactor: 将 Redux 迁移至 Zustand

重构状态管理方案，优势：
- 减少样板代码
- 更好的 TypeScript 支持
- 降低包体积 50%

使用场景：

优化代码结构
提取公共逻辑
重命名变量/函数以提高可读性

6. `perf` - 性能优化

提升性能的代码变更。

# 优化查询
perf(database): 为用户表添加索引

# 缓存优化
perf: 使用 React.memo 优化组件渲染

# 资源优化
perf(images): 启用 WebP 格式压缩图片

优化结果：首屏加载时间从 3.2s 降至 1.1s

使用场景：

数据库查询优化
前端渲染优化
资源加载优化

7. `test` - 测试相关

添加或修改测试代码。

# 添加单元测试
test(auth): 为登录功能添加单元测试

# 修复测试
test: 修复因 API 变更导致的测试失败

# E2E 测试
test(e2e): 添加用户注册流程的端到端测试

使用场景：

新增单元测试
补充集成测试
修复失败的测试用例

8. `build` - 构建系统

影响构建系统或外部依赖的变更。

# 依赖更新
build: 升级 React 至 v19.0.0

# 构建配置
build(webpack): 优化生产环境打包配置

# 依赖管理
build: 移除未使用的依赖包

删除以下依赖：
- lodash (使用原生 ES6 替代)
- moment (迁移至 date-fns)

使用场景：

升级/降级依赖版本
修改 Webpack/Vite 配置
调整打包策略

9. `ci` - 持续集成

修改 CI/CD 配置文件或脚本。

# GitHub Actions
ci: 添加自动部署到生产环境的 workflow

# 测试覆盖率
ci: 集成 Codecov 代码覆盖率检查

# Docker 配置
ci(docker): 优化镜像构建缓存策略

使用场景：

修改 GitHub Actions/GitLab CI 配置
调整自动化测试流程
优化 Docker 构建

10. `chore` - 其他杂项

不属于以上类型的其他变更。

# 配置文件
chore: 更新 .gitignore 忽略规则

# 脚本工具
chore: 添加数据库迁移脚本

# 依赖维护
chore: 更新开发依赖至最新版本

使用场景：

修改配置文件
更新开发工具
不影响源代码的变更

11. `revert` - 回滚

撤销之前的提交。

# 回滚提交
revert: 回滚 "feat: 添加实验性功能"

This reverts commit a1b2c3d4.

原因：该功能在生产环境导致性能问题

使用场景：

撤销有问题的提交
回退不稳定的功能

作用域（Scope）的使用

作用域用于标识变更影响的模块或范围，常见示例：

feat(auth): 添加 OAuth2 登录
fix(ui): 修复按钮样式错误
perf(api): 优化用户列表查询接口
docs(readme): 更新快速开始指南

常见作用域示例

前端项目：

components - 组件
pages - 页面
store - 状态管理
router - 路由
utils - 工具函数

后端项目：

api - API 接口
database - 数据库
middleware - 中间件
auth - 认证/授权
config - 配置

全栈通用：

deps - 依赖
security - 安全
i18n - 国际化

破坏性变更（Breaking Changes）

当提交包含不兼容的 API 变更时，需要特殊标注。

方式 1：使用感叹号

feat!: 移除对 IE11 的支持

BREAKING CHANGE: 不再支持 Internet Explorer 11
建议用户升级至现代浏览器（Chrome/Firefox/Edge）

refactor(api): 重构用户接口返回格式

BREAKING CHANGE: 用户接口返回结构变更
旧格式：{ data: { user: {...} } }
新格式：{ user: {...} }

迁移指南：https://docs.example.com/migration-v2

关联 Issue

在 Footer 中关联相关的 Issue 或 PR：

fix(api): 修复用户注册邮箱验证失败

修复了正则表达式错误，现在支持所有合法邮箱格式

Closes #123
Fixes #456, #789
Related to #101

常用关键词：

Closes / Fixes - 关闭 Issue
Resolves - 解决 Issue
Related to - 相关 Issue
Refs - 引用 Issue

实践建议

✅ 推荐做法

1. 使用祈使句，现在时

✅ feat: 添加用户导出功能
✅ fix: 修复内存泄漏问题

❌ feat: 已添加用户导出功能
❌ fix: 修复了内存泄漏问题

2. 首字母小写（英文）或无需大写（中文）

✅ feat: add user export feature
✅ feat: 添加用户导出功能

❌ feat: Add user export feature

3. 结尾不加句号

✅ docs: 更新 API 文档
❌ docs: 更新 API 文档。

4. 主题简明扼要（< 50 字符）

✅ fix: 修复登录状态丢失
❌ fix: 修复了当用户在登录后刷新页面时会导致登录状态丢失的问题

5. 一次提交只做一件事

✅
  feat: 添加暗黑模式
  fix: 修复按钮点击无响应

❌
  feat: 添加暗黑模式并修复按钮点击无响应

⚠️ 常见错误

1. 类型错误

❌ feature: 添加新功能  # 应该用 feat
❌ bugfix: 修复问题     # 应该用 fix
❌ update: 更新文档     # 应该用 docs

2. 混淆 style 和 feat

❌ style: 添加暗黑模式样式  # style 是格式化，这应该是 feat(ui)
✅ feat(ui): 添加暗黑模式样式

3. 提交粒度过大

❌ feat: 实现整个用户管理模块

# 应该拆分成多个提交
✅ feat(user): 添加用户列表页面
✅ feat(user): 添加用户创建功能
✅ feat(user): 添加用户编辑功能
✅ feat(user): 添加用户删除功能

工具推荐

1. Commitizen - 交互式提交

# 安装
npm install -g commitizen
cz-conventional-changelog

# 使用
git cz  # 代替 git commit

执行后会有交互式提示，引导你填写规范的提交信息。

2. Commitlint - 提交信息校验

# 安装
npm install --save-dev @commitlint/cli @commitlint/config-conventional

# 配置 commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional']
}

# 结合 Husky 使用
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

3. Standard Version - 自动生成 Changelog

# 安装
npm install --save-dev standard-version

# 使用
npm run release

# 自动：
# 1. 根据提交历史确定版本号
# 2. 生成 CHANGELOG.md
# 3. 创建 Git Tag

实际案例对比

案例 1：功能开发

❌ 不规范

git commit -m "update"
git commit -m "add some files"
git commit -m "fix bug"

✅ 规范

git commit -m "feat(cart): 添加购物车商品数量修改功能"
git commit -m "style(cart): 格式化购物车组件代码"
git commit -m "fix(cart): 修复删除商品后总价未更新的问题"

案例 2：依赖升级

❌ 不规范

git commit -m "update dependencies"

✅ 规范

build(deps): 升级核心依赖至最新稳定版

- React: 18.2.0 → 19.0.0
- TypeScript: 5.2.2 → 5.3.3
- Vite: 5.0.0 → 5.1.0

测试通过，无破坏性变更

案例 3：紧急修复

❌ 不规范

git commit -m "hotfix"

✅ 规范

fix(auth): 修复生产环境 Token 过期导致的登出问题

问题描述：服务器时区设置错误导致 Token 提前过期
解决方案：统一使用 UTC 时间戳进行验证

Fixes #1234
Priority: Critical

总结

规范的 Git 提交信息是团队协作的重要实践：

核心类型要记牢：feat（新功能）、fix（修复）、docs（文档）、style（格式）、refactor（重构）、perf（性能）、test（测试）、build（构建）、ci（持续集成）、chore（杂项）
格式统一很重要：<type>(<scope>): <subject> 是基础，复杂变更补充 body 和 footer
一次提交一件事：小步快跑，便于回滚和追溯
善用工具提效率：Commitizen、Commitlint、Standard Version 让规范落地更简单
团队共识是关键：制定符合自己团队的规范，并坚持执行

记住：清晰的提交历史就像是代码的时光机，让未来的你和团队成员能够快速理解每一次变更的来龙去脉。

Git 提交信息规范指南：常用类型与最佳实践

后记

评论 (0)