# Conventional Commits 快速参考

*提交格式、类型、作用域、破坏性变更*

> Source: Conventional Commits (conventionalcommits.org) · MIT

## 格式

### 提交消息结构

```
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
```

### 各部分说明

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

### 规则

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

## 类型

### 核心类型（影响 SemVer）

| Command | Description |
|---------|-------------|
| `feat` | 新功能（触发 MINOR 版本升级） |
| `fix` | Bug 修复（触发 PATCH 版本升级） |

### 扩展类型（通用约定）

| Command | Description |
|---------|-------------|
| `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
```

### 作用域命名指南

| Command | Description |
|---------|-------------|
| `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.
```

### 规则

| Command | Description |
|---------|-------------|
| `! 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

| Command | Description |
|---------|-------------|
| `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
```

### 常用工具

| Command | Description |
|---------|-------------|
| `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)
```

## 常用模式

### 版本升级映射

| Command | Description |
|---------|-------------|
| `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.
```