格式

提交消息结构

[optional scope]: 
[optional body]
[optional footer(s)]

各部分说明

type	变更类别（feat、fix 等）
scope	受影响的代码区域（可选）
description	用祈使语气写的简短摘要
body	详细说明（可选，空行后）
footer	元数据，如 BREAKING CHANGE 或 issue 引用

规则

Imperative mood	用 "add feature" 而非 "added feature"
Lowercase type	feat: 而非 Feat:
No period	描述末尾不加句号
Blank line	body/footer 与描述之间空一行

类型

核心类型（影响 SemVer）

feat	新功能（触发 MINOR 版本升级）
fix	Bug 修复（触发 PATCH 版本升级）

扩展类型（通用约定）

build	构建系统或外部依赖
chore	维护任务（不涉及源码/测试变更）
ci	CI 配置与脚本
docs	仅文档变更
perf	性能优化
refactor	既不修复 bug 也不添加功能的代码重构
revert	回退某次提交
style	格式、空白（非 CSS 样式）
test	添加或修正测试

作用域

作用域用法

feat(auth): add OAuth2 login flow
fix(parser): handle empty input gracefully
docs(readme): update installation steps
refactor(api): extract validation middleware

作用域命名指南

Module name	feat(auth):、fix(parser):
Layer name	feat(api):、fix(db):
Feature area	feat(search):、fix(checkout):
Dependency	build(deps):、chore(npm):
Omit if broad	跨模块变更时省略作用域

破坏性变更

标记破坏性变更

feat!: remove deprecated login endpoint
feat(api)!: change response format to JSON:API
fix!: drop Node 14 support

Footer 形式的破坏性变更

feat(api): change user endpoint response
BREAKING CHANGE: response now returns array
instead of object. Update client parsing.

规则

! after type/scope	破坏性变更的简写标记
BREAKING CHANGE:	Footer token（必须全大写）
BREAKING-CHANGE:	同样有效（连字符形式）
SemVer impact	触发 MAJOR 版本升级
Any type	任何类型都可以有破坏性变更

示例

简单提交

feat: add email notifications
fix: prevent race condition in checkout
docs: correct typo in contributing guide
style: format with prettier
refactor: simplify error handling logic

带作用域

feat(blog): add comment threading
fix(auth): refresh token before expiry
test(api): add missing edge case coverage
ci(github): add Node 20 to test matrix

带 body 和 footer

fix(parser): handle nested quotes correctly

Previously, nested quotes caused the parser
to enter an infinite loop. This adds a depth
counter to prevent unbounded recursion.

Closes #234

Footer

Footer Token

BREAKING CHANGE:	描述破坏性 API 变更
Closes #123	合并时自动关闭 issue
Fixes #456	自动关闭 issue（fix 引用）
Refs #789	引用 issue 但不关闭
Reviewed-by: name	审阅者署名
Co-authored-by: name	共同作者署名

多个 Footer

feat(api)!: redesign authentication flow

Migrate from session-based to JWT auth.

BREAKING CHANGE: /auth endpoints changed
Closes #101
Refs #98, #99

工具链

提交 Lint

npm install -D @commitlint/cli \
  @commitlint/config-conventional
echo "module.exports = { extends: \
  ['@commitlint/config-conventional'] }" \
  > commitlint.config.js

常用工具

commitlint	按规范 lint 提交消息
husky	Git hooks（提交时运行 commitlint）
commitizen (cz)	交互式提交消息生成器
standard-version	自动生成 changelog + 版本升级
semantic-release	全自动发布流水线
release-please	Google 的发布自动化工具

Commitizen 设置

npm install -D commitizen \
  cz-conventional-changelog
npx commitizen init cz-conventional-changelog
# Use: npx cz (or git cz with alias)

常用模式

版本升级映射

fix:	PATCH（1.0.0 → 1.0.1）
feat:	MINOR（1.0.0 → 1.1.0）
BREAKING CHANGE	MAJOR（1.0.0 → 2.0.0）
docs:、style: 等	不升级版本

Changelog 分组

## [1.2.0] - 2026-03-27
### Features
- add email notifications (abc1234)
### Bug Fixes
- prevent race condition (#123) (def5678)

回退格式

revert: feat(blog): add comment threading
This reverts commit abc1234def5678.

CONVENTIONAL COMMITS 快速参考