1️⃣ feat — 新功能

用途：添加应用程序的新功能或特性

使用场景

• 新增用户可见的功能
• 新增 API 端点
• 新增组件/模块
• 新增配置选项

示例

# 简单功能
feat: add dark mode toggle

# 带范围
feat(auth): add OAuth2 login with Google

# 带详细说明
feat(cart): implement shopping cart persistence

Add localStorage support for cart items.
Cart now survives page refresh and browser restart.

Closes #234

# Breaking change
feat!: change API response format from XML to JSON

判断标准

• ✅ 用户/开发者能感知到的新能力
• ✅ 之前不存在的功能
• ❌ 不是 bug 修复
• ❌ 不是代码重构

---

2️⃣ fix — Bug 修复

用途：修复应用程序中的错误或问题

使用场景

• 修复运行时错误
• 修复逻辑错误
• 修复边界条件
• 修复回归问题

示例

# 简单修复
fix: prevent crash when user input is null

# 带范围
fix(auth): handle expired JWT tokens correctly

# 带详细说明
fix(api): retry failed requests with exponential backoff

Previously, failed API calls would immediately throw.
Now implements 3 retries with exponential backoff:
- 1st retry: 1 second
- 2nd retry: 2 seconds  
- 3rd retry: 4 seconds

Fixes #567

# 修复安全漏洞
fix(security): sanitize user input to prevent XSS

BREAKING CHANGE: HTML tags now stripped from user input

判断标准

• ✅ 修复了预期行为的偏差
• ✅ 解决了用户报告的问题
• ✅ 修复了安全漏洞
• ❌ 不是新功能
• ❌ 不是性能优化

---

3️⃣ docs — 文档更新

用途：仅修改文档，不涉及代码逻辑变更

使用场景

• 更新 README
• 添加/修改 API 文档
• 更新注释
• 添加示例代码
• 更新 CHANGELOG

示例

# 简单文档更新
docs: update installation instructions

# 带范围
docs(api): add authentication endpoint examples

# 添加新文档
docs: add contributing guidelines

# 修复文档错误
docs: correct typos in README

# 更新代码注释
docs(utils): improve JSDoc comments for date helpers

判断标准

• ✅ 只修改 .md 文件
• ✅ 只修改代码注释
• ✅ 只修改文档字符串
• ❌ 如果同时修改了代码，使用其他类型

---

4️⃣ style — 格式/样式（无逻辑变更）

用途：代码格式调整，不影响代码逻辑或功能

使用场景

• 代码缩进调整
• 空格/换行调整
• 引号风格统一
• 分号添加/移除
• CSS 样式微调

示例

# 代码格式
style: fix indentation in utils.ts

# 引号统一
style: convert single quotes to double quotes

# 空行调整
style: remove trailing whitespace

# CSS 微调
style(ui): adjust button padding and margins

# ESLint/Prettier 格式化
style: apply prettier formatting

判断标准

• ✅ 不改变代码功能
• ✅ 不改变代码逻辑
• ✅ 只是视觉/格式调整
• ❌ 如果重构了代码结构，使用 refactor

---

5️⃣ refactor — 重构（无功能/修复）

用途：改进代码结构而不改变外部行为

使用场景

• 提取公共函数
• 重命名变量/函数
• 简化复杂逻辑
• 改善代码组织
• 消除代码重复

示例

# 提取函数
refactor(auth): extract token validation logic

# 重命名
refactor: rename UserService to AccountService

# 简化逻辑
refactor(api): simplify error handling with try-catch

# 改善结构
refactor(db): extract query builder to separate module

# 消除重复
refactor(utils): consolidate duplicate date formatting code

# 设计模式应用
refactor(strategy): implement strategy pattern for payment methods

判断标准

• ✅ 外部行为不变
• ✅ 内部结构改善
• ✅ 可读性/可维护性提升
• ❌ 如果添加了新功能，使用 feat
• ❌ 如果修复了 bug，使用 fix

---

6️⃣ perf — 性能优化

用途：改善应用程序性能而不改变功能

使用场景

• 减少内存使用
• 提高执行速度
• 优化数据库查询
• 减少网络请求
• 实现缓存

示例

# 缓存优化
perf: cache user sessions in Redis

# 查询优化
perf(db): add index to speed up user lookups

# 减少请求
perf(api): batch API calls to reduce HTTP requests

# 内存优化
perf: implement object pooling for heavy resources

# 算法优化
perf(algorithm): replace O(n²) loop with O(n) hashmap lookup

# 懒加载
perf(images): implement lazy loading for gallery thumbnails

判断标准

• ✅ 可测量的性能提升
• ✅ 功能行为不变
• ✅ 减少资源消耗
• ❌ 如果改变了功能，使用 feat
• ❌ 如果是架构调整，使用 refactor

---

7️⃣ test — 测试相关

用途：添加、修改或删除测试代码

使用场景

• 添加单元测试
• 添加集成测试
• 修复测试用例
• 更新测试快照
• 添加测试工具

示例

# 添加测试
test: add unit tests for UserService

# 带范围
test(auth): add integration tests for login flow

# 修复测试
test: fix flaky test in user registration

# 更新快照
test(ui): update component snapshots

# 添加测试配置
test: configure Jest for TypeScript support

# 测试工具
test(utils): add test helper for mocking API responses

判断标准

• ✅ 只修改测试文件
• ✅ 添加新的测试用例
• ✅ 修复或改进现有测试
• ❌ 如果同时修复了代码，使用 fix
• ❌ 如果同时添加了功能，使用 feat

---

8️⃣ build — 构建系统/依赖

用途：修改构建系统或外部依赖

使用场景

• 升级依赖版本
• 添加新依赖
• 移除依赖
• 修改构建配置
• 修改打包工具

示例

# 升级依赖
build: upgrade webpack to v5

# 添加依赖
build: add TypeScript support

# 移除依赖
build: remove unused lodash dependency

# 构建配置
build(webpack): optimize production bundle size

# 包管理器
build: migrate from npm to pnpm

# 打包优化
build: enable tree shaking for smaller bundles

# Breaking change
build!: drop support for Node.js 14

判断标准

• ✅ 修改 package.json
• ✅ 修改 webpack/vite/rollup 配置
• ✅ 修改 Dockerfile
• ✅ 修改 CI/CD 构建步骤
• ❌ 如果修改了 CI 运行配置，使用 ci

---

9️⃣ ci — CI/配置变更

用途：修改持续集成、持续部署或自动化配置

使用场景

• 添加 CI 流水线
• 修改 GitHub Actions
• 修改 Jenkins 配置
• 添加自动化脚本
• 修改部署配置

示例

# 添加 CI
ci: add GitHub Actions workflow for testing

# 修改 CI
ci: update Node.js version in CI matrix

# 部署配置
ci: add staging deployment step

# 自动化
ci(github): add automatic dependency updates with Dependabot

# 代码质量
ci: add ESLint check to CI pipeline

# 发布流程
ci: configure automatic npm publish on release

判断标准

• ✅ 修改 .github/workflows/
• ✅ 修改 Jenkinsfile
• ✅ 修改 .gitlab-ci.yml
• ✅ 修改部署脚本
• ❌ 如果修改了应用构建配置，使用 build

---

🔟 chore — 维护/杂项

用途：不修改 src 或 test 文件的维护性工作

使用场景

• 更新 .gitignore
• 清理无用文件
• 更新许可证
• 修改项目配置
• 杂项维护

示例

# 清理代码
chore: clean up unused imports

# 配置文件
chore: update .gitignore

# 许可证
chore: update LICENSE year

# 项目配置
chore: configure editor settings

# 杂项
chore: add CODEOWNERS file

# 版本号
chore: bump version to 2.0.0

# 依赖清理
chore: remove console.log statements

判断标准

• ✅ 不影响功能
• ✅ 不影响测试
• ✅ 维护性工作
• ✅ 无法归类到其他类型
• ❌ 如果能归类到其他类型，优先使用其他类型

---

1️⃣1️⃣ revert — 回滚提交

用途：撤销之前的提交

使用场景

• 回滚有问题的功能
• 回滚错误的修复
• 撤销误提交

示例

# 简单回滚
revert: remove broken feature

# 指定回滚的提交
revert(auth): revert OAuth2 implementation

This reverts commit abc123def456.

# 回滚多个提交
revert: revert changes from v1.2.0

Reverts commits:
- abc123: feat(auth): add OAuth2
- def456: fix(auth): handle edge cases

格式要求

revert: <被回滚提交的 header>

This reverts commit <commit hash>.

<可选：回滚原因>

判断标准

• ✅ 撤销之前的提交
• ✅ 包含被回滚的 commit hash
• ✅ 说明回滚原因
• ❌ 不是手动删除代码

---

📊 类型选择决策树

你的改动是什么？
│
├─ 添加了新功能？ ──────────────→ feat
│
├─ 修复了 bug？ ────────────────→ fix
│
├─ 只改了文档？ ────────────────→ docs
│
├─ 只改了格式（无逻辑变更）？ ──→ style
│
├─ 改善代码结构（无功能变更）？ ─→ refactor
│
├─ 提升了性能？ ────────────────→ perf
│
├─ 只改了测试？ ────────────────→ test
│
├─ 改了构建/依赖？ ─────────────→ build
│
├─ 改了 CI/CD 配置？ ───────────→ ci
│
├─ 维护性工作（无法归类）？ ─────→ chore
│
└─ 撤销之前的提交？ ────────────→ revert

---

⚠️ 常见错误

错误做法	正确做法
fix: add new validation	feat: add input validation
feat: fix login bug	fix: resolve login failure
chore: update dependencies	build: upgrade webpack to v5
style: refactor user service	refactor: improve user service structure
update README (无类型)	docs: update README installation guide