前言
在团队协作开发中，你是否曾经遇到过以下困扰？
- 查看 Git 历史时无法快速理解每次提交的意图
- 无法自动生成有意义的变更日志（CHANGELOG）
- 版本号管理混乱，缺乏明确的语义化版本控制
- 新成员难以快速理解项目的演进历程
这些问题都可以通过 Conventional Commits（约定式提交） 规范来解决。本文将带你全面了解并实践这一强大的开发规范。
理解 Conventional Commits
什么是 Conventional Commits？
Conventional Commits 是一种轻量级的提交信息约定，它提供了一组简单的规则来创建清晰的提交历史。
基本格式
<类型>[可选的作用域]: <描述>
[可选的正文]
[可选的脚注]
提交类型说明
| 类型 | 说明 | 示例 |
|---|---|---|
feat | 新功能 | feat: 添加用户登录功能 |
fix | 修复 bug | fix: 修复登录页面样式错乱 |
docs | 文档更新 | docs: 更新 API 使用说明 |
style | 代码格式调整 | style: 调整代码缩进 |
refactor | 重构代码 | refactor: 优化用户验证逻辑 |
test | 测试相关 | test: 添加用户服务单元测试 |
chore | 构建过程或辅助工具变动 | chore: 更新 webpack 配置 |
安装与配置
全局安装（适合个人使用）
# 安装 Commitizen
npm install -g commitizen cz-conventional-changelog
# 配置适配器，告诉Commitizen使用了哪个规范
echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc
项目本地安装（推荐团队使用）
安装到开发依赖
npm install --save-dev commitizen cz-conventional-changelog
配置 package.json
{
"scripts": {
"commit": "cz"
},
"config": {
"commitizen": {
"path": "./node_modules/cz-conventional-changelog"
}
}
}
具体使用
基础使用
基本提交流程
# 1. 添加文件到暂存区
git add src/components/Login.js
# 2. 使用交互式提交
git cz
基础交互示例
场景：开发用户登录功能
# 选择类型
? Select the type of change that you're committing:
feat: A new feature
fix: A bug fix
docs: Documentation only changes
❯ style: Changes that do not affect the meaning of the code
refactor: A code change that neither fixes a bug nor adds a feature
test: Adding missing tests or correcting existing tests
# 可选作用域(如修改的模块)
? What is the scope of this change (e.g. component or file name): auth
# 描述
? Write a short, imperative tense description of the change: add login component
# 可选的正文
? Provide a longer description of the change: 实现用户登录页面，包含表单验证和错误处理
# 是否有破坏性变更
? Are there any breaking changes? (y/N) n
# 是否解决了某个 open issue
? Does this change affect any open issues? (y/N) n
生成的提交信息：
feat(auth): add login component
实现用户登录页面，包含表单验证和错误处理
高级使用
处理破坏性变更
场景：重构支付 API
? Select the type of change that you're committing: feat
? What is the scope of this change: payment
? Write a short, imperative tense description of the change: migrate to new payment API
? Provide a longer description of the change: 重构支付服务接口，提升性能和安全性
? Are there any breaking changes? (y/N) y
? Describe the breaking changes: 移除旧的PaymentService.v1，所有支付接口需要更新到v2版本
? Does this change affect any open issues? (y/N) y
? Add issue references: Closes #156
生成的提交信息：
feat(payment): migrate to new payment API
重构支付服务接口，提升性能和安全性
BREAKING CHANGE: 移除旧的PaymentService.v1，所有支付接口需要更新到v2版本
Closes #156
Issue 引用前缀含义以及关联多个 Issue
Issue 引用前缀
| 前缀 | 含义 | 示例 | 说明 |
|---|---|---|---|
fix | 修复问题 | fix #123 | 这个提交修复了 #123 号 issue |
close / closes | 关闭问题 | close #123 | 这个提交会关闭 #123 号 issue |
resolve / resolves | 解决问题 | resolve #123 | 这个提交解决了 #123 号 issue |
re | 参考关联 | re #123 | 这个提交与 #123 相关，但不直接修复 |
see | 参见 | see #123 | 参考 #123 获取更多信息 |
场景：修复认证相关问题
? Select the type of change that you're committing: fix
? What is the scope of this change: auth
? Write a short, imperative tense description of the change: resolve authentication issues
? Provide a longer description of the change: 修复用户认证超时和token刷新问题
? Are there any breaking changes? (y/N) n
? Does this change affect any open issues? (y/N) y
? Add issue references: fix #123
fix #124
re #125
? Would you like to add more issue references? (y/N) n
生成的提交信息：
fix(auth): resolve authentication issues
修复用户认证超时和token刷新问题
fix #123
fix #124
re #125
