约定式提交（Conventional Commits）

约定式提交（Conventional Commits）是一套给 Git 提交信息（commit message）用的统一格式规范，目的是让提交历史更清晰、可读，并且能被工具自动解析，从而实现：

• 自动生成更新日志（CHANGELOG）
• 自动决定版本号（遵循语义化版本 SemVer：major/minor/patch）
• 更容易做代码审查、回滚、定位变更
• 更规范的团队协作与 CI/CD 流程

基本格式

常见的提交信息长这样：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

例如：

• feat: add user login API
• fix(auth): handle token refresh error
• docs: update README
• refactor: simplify payment flow

1) type（类型）

最常用的类型有：

• feat：新增功能（通常对应 minor 版本）
• fix：修复 bug（通常对应 patch 版本）
• docs：文档变更
• style：格式调整（不影响逻辑，比如空格、分号）
• refactor：重构（既不是新增功能也不是修 bug）
• perf：性能优化
• test：测试相关
• build：构建系统/依赖相关（如 webpack、pnpm）
• ci：CI 配置相关
• chore：杂项/维护性工作（不改业务逻辑）
• revert：回滚某次提交

2) scope（可选的影响范围）

用来说明影响的模块/领域，例如：

• feat(ui): add dark mode
• fix(api): correct pagination

scope 没有统一标准，团队自己约定即可。

3) description（简短描述）

一句话说明做了什么，通常用祈使句风格（add / fix / update），不要太长。

重大变更（Breaking Change）怎么写？

如果这次改动会破坏兼容性（比如 API 改了、字段删了），需要明确标识。常见两种写法：

写法 A：在 type 后加 !

feat!: remove legacy auth endpoint

写法 B：在 footer 写 BREAKING CHANGE

feat(auth): change token format

BREAKING CHANGE: token is now JWT v2; old tokens are invalid

重大变更一般会触发 major 版本升级。

为什么团队会推它？

• 可机器解析：工具能读懂 feat/fix、scope、breaking change
• 更一致：减少“修了一些东西”“update”这种模糊提交
• 更可追踪：快速过滤出某模块的变更

常见生态工具包括：commitlint（校验格式）、semantic-release（自动发版）、standard-version（生成 changelog + bump 版本）等。

参考资料

https://www.conventionalcommits.org/zh-hans/v1.0.0/