
---
#领域/未知

#复盘/0 #临时/备忘 #状态/待处理

## 一句话描述

[____git **Conventional Commits（约定式提交）** 规范____]

注意：请忽略以上内容

---

## 操作需求

问题描述是【输入内容】，请专业耐心的解答我的问题，并将你的答案整理归纳至【输出内容】

## 内容要求

1. 结论先行，主次分明：先给出「一句话核心结论」，再分点给出细节
2. 逐层递进逻辑链：原理->知识点->用法->案例，理解本质再应用
3. 实操为王，案例全覆盖：所有知识点必须配备「可实现的案例」
4. 避坑指南，强制标配：必须单独列出易踩坑点+精准解决方案
5. 融会贯通：讲解单个知识点时，必须主动关联同类/互补工具，明确差异、标准、场景，帮助建立知识体系
6. 浓缩总结，提炼精华，方便记忆：提炼所有重点为极简内容，方便复习和快速查阅
7. 语言风格：口语化、专业但不晦涩，复杂概念用「大白话 + 示例」解释，拒绝堆砌专业术语；所有命令 / 代码 / 参数格式工整，带中文注释，一目了然。
8. 内容结构：层级清晰，用标题 / 分点做区分，核心内容加粗标注，代码块独立展示，重点规则用「✅ 黄金规则」「⚠️ 避坑点」「💡 核心技巧」做醒目标注，阅读体验极佳。
9. 无冗余内容：不拓展无关知识点、不做无意义的参数罗列、不写复杂冷门用法，所有内容都围绕「吃透核心 + 落地实战」，精准匹配学习需求，不浪费时间。
10. 知识联动要求：当讲解后续内容时，必须主动关联之前讲解过的内容，形成知识闭环。
11. 联动案例：必须是高频使用场景
12. 

## 输出格式

- [x] markdown

```markdown
## 一句话描述

【使用一句话概括】

## 详细解释

【你的解答】

## 延伸补充

...
### 常见避坑点

### 知识点浓缩

【背诵级，解决反复查资料的核心需求】

### 进阶优化方向

## 提问建议
...

---
```

## 注意
1. 请判断勾选框是否处于被勾选状态，例如markdown勾选框处于未被勾选状态，则无需输出markdown格式

以上内容为系统提示，为了辅助你更好的回答。

--- 

## 输入内容

| 项目     | 内容                                             |
| ------ | ---------------------------------------------- |
| 你的角色设定 | 你是一位结构化、体系化的[__软件工程,git______]教学专家，定位为精准知识的输出者 |
| 上下文    | **Conventional Commits（约定式提交）** 规范；git 提交      |
| 约束     |                                                |
| 任务目标   | 熟悉**Conventional Commits（约定式提交）** 规范，并应用到实际场景中 |
| 解决问题   | git 提交时提交混乱随意                                  |
| 服务于    | 项目更好的推进、管理                                     |
|        |                                                |

---

注意：请忽略以下内容

## 输出内容
## 一句话描述

约定式提交是一套标准化 Git 提交信息格式，通过固定结构规范提交日志，解决提交混乱问题，同时支持自动化生成版本、日志与项目管理。

## 详细解释

### 一、核心原理

本质是给 Git 提交信息定 “统一语法”，让提交日志从 “随意文字” 变成 “机器可读 + 人易理解” 的结构化数据，既方便团队协作，也能对接自动化工具（如生成 CHANGELOG、自动发版）。

### 二、核心知识点（结构 + 规则）

提交信息的标准结构（必选 + 可选）：

```plaintext
<type>(<scope>): <subject>
// 空行
<body>
// 空行
<footer>
```

#### 1. 必选核心：<type>（提交类型）

✅ 黄金规则：**type 必须是固定枚举值，禁止自定义**，核心常用类型：

- `feat`：新功能（对应 SemVer 的 MINOR 版本）
- `fix`：修复 Bug（对应 SemVer 的 PATCH 版本）
- `docs`：仅文档修改（README、注释等）
- `style`：代码格式调整（不影响代码逻辑，如空格、分号）
- `refactor`：重构（既不是新功能也不是 Bug 修复，如代码优化、变量重命名）
- `test`：测试相关（新增 / 修改测试用例，不修改业务代码）
- `chore`：构建 / 工具 / 依赖调整（如打包配置、依赖更新、脚本修改）

#### 2. 可选：<scope>（影响范围）

标注修改的模块 / 文件 / 功能，用小括号包裹，无范围可省略括号，例：`feat(login): 新增登录验证码`。

#### 3. 必选：<subject>（简短描述）

✅ 黄金规则：**不超过 50 字符，动词开头、小写开头、无结尾标点**，清晰说明 “做了什么”。

#### 4. 可选：<body>（详细说明）

换行后写具体修改原因、实现逻辑，每行不超过 72 字符，解释 “为什么改”。

#### 5. 可选：<footer>（脚注）

用于关联 Issue、标注破坏性变更，格式：

- 关联 Issue：`Closes #123`（关闭 Issue 123）
- 破坏性变更：`BREAKING CHANGE: 移除旧版登录接口`（对应 SemVer 的 MAJOR 版本）

### 三、实操用法

1. 简单提交：直接按格式写单行信息

bash

```
git commit -m "fix(user): 修复用户昵称过长截断问题"
```

2. 复杂提交：用多行（body+footer），通过`git commit`（不带 - m）进入编辑器编写。

### 四、全覆盖实战案例

1. 新功能提交

plaintext

```
feat(pay): 新增微信支付渠道
支持微信扫码支付，对接微信支付V3接口
Closes #45
```

2. Bug 修复提交

plaintext

```
fix(cart): 修复购物车商品数量计算错误
解决商品数量为0时仍显示的问题，修正数量校验逻辑
```

3. 文档修改

plaintext

```
docs: 更新README部署步骤
补充Docker部署的环境变量配置说明
```

4. 代码重构

plaintext

```
refactor(api): 重构用户信息查询接口
拆分接口逻辑，提升查询性能，不改变接口入参出参
```

5. 测试用例新增

plaintext

```
test(order): 新增订单支付超时测试用例
覆盖支付超时自动取消的场景测试
```

6. 构建配置调整

plaintext

```
chore: 升级webpack到5.0版本
优化打包体积，移除废弃插件
```

7. 破坏性变更

plaintext

```
feat(auth): 重构权限校验逻辑
BREAKING CHANGE: 移除旧版token校验方式，统一使用JWT
```

## 延伸补充

### 一、关联工具 / 标准

1. **commitlint**：校验提交信息是否符合约定式提交规范，避免违规提交
2. **husky**：Git 钩子工具，配合 commitlint 在提交前自动校验
3. **语义化版本（SemVer）**：约定式提交是 SemVer 的 “落地载体”，type 直接对应版本升级规则（feat→MINOR、fix→PATCH、BREAKING CHANGE→MAJOR）
4. **standard-version**：基于约定式提交自动生成 CHANGELOG、升级版本、打 Tag

### 二、与其他提交规范的差异

- 对比 “随意提交”（如`fix bug`、`修改代码`）：结构化、可自动化，团队协作无歧义
- 对比 “Angular 提交规范”：约定式提交是 Angular 规范的简化通用版，更易落地，无过度复杂的 type 限制

---

### 常见避坑点

⚠️ 避坑 1：type 自定义（如用`add`代替`feat`）

解决方案：严格使用核心 7 种 type，禁止自创，团队统一枚举表。

⚠️ 避坑 2：subject 过长 / 带标点 / 大写开头（如`Fix: 修复了登录失败的问题，这个问题很严重`）

解决方案：控制在 50 字符内，小写动词开头，去掉句号、感叹号。

⚠️ 避坑 3：scope 滥用（如写`fix(all): 修复所有问题`）

解决方案：scope 精准到模块，无具体范围直接省略，不写模糊值。

⚠️ 避坑 4：忽略 footer 的破坏性变更标注

解决方案：涉及接口删除、参数移除等 breaking 变更，必须加`BREAKING CHANGE:`脚注，避免线上风险。

⚠️ 避坑 5：style 和 refactor 混淆（把代码逻辑优化写成 style）


