博客快捷键

按住 Shift 键查看可用快捷键

ShiftK

开启/关闭快捷键功能

ShiftA

打开/关闭中控台

ShiftD

深色/浅色显示模式

ShiftS

站内搜索

ShiftR

随机访问

ShiftH

返回首页

ShiftL

友链页面

ShiftP

关于本站

ShiftI

原版/本站右键菜单

松开 Shift 键或点击外部区域关闭

文章详情

互动

Git 约定式提交规范

268214分钟2026-08-1618未知0

Conventional Commits（约定式提交）

规范地址：https://www.conventionalcommits.org/

快速参考

场景	命令
新功能	`feat: 添加用户注册功能`
修 Bug	`fix: 修复空指针异常`
改文档	`docs: 更新 README 安装说明`
重构	`refactor: 提取公共工具函数`
性能优化	`perf: 优化列表渲染性能`
格式调整	`style: 统一代码缩进`
加测试	`test: 增加登录模块单元测试`
构建变更	`build: 升级 webpack 到 5.x`
CI 变更	`ci: 调整 GitHub Actions 流程`
杂项	`chore: 更新依赖版本`
回滚	`revert: 回滚添加暗黑模式`
带 Scope	`feat(auth): 支持手机号验证码登录`
破坏性变更	`feat!: 重构用户认证接口`
关联 Issue	`feat: 支持手机号登录\n\nCloses #128`

1. 格式

PLAINTEXT

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

部分	必填	说明
type	是	变更性质
scope	否	影响模块（小写英文，`-` 连接）
description	是	简短描述（祈使句，首字母小写，不加句号，≤50 字符）
body	否	详细说明（动机、实现方式、影响）
footer	否	关联 Issue、破坏性变更声明

2. Type 清单

Type	含义	好例子	坏例子
`feat`	新增功能	`feat: 支持微信登录`	`feat: 添加了订单功能。`（过去时+句号）
`fix`	修复 Bug	`fix: 修复支付金额计算错误`	`Fix: 修复空指针`（首字母大写）
`docs`	文档变更	`docs: 更新 README 安装说明`	`docs: 修改readme`（描述不够明确）
`style`	格式调整（不影响逻辑）	`style: 统一代码缩进为2空格`	`style: 改了个格式`（没说明改了啥）
`refactor`	重构（非功能非修复）	`refactor: 提取公共工具函数`	`refactor: 重写一大堆`（太模糊）
`perf`	性能优化	`perf: 优化列表虚拟滚动渲染`	`perf: 快了`（无量化描述）
`test`	测试相关	`test: 增加登录模块单元测试`	`test: 加测试`（没说明测什么）
`build`	构建系统/外部依赖变更	`build: 升级 webpack 到 5.x`	`build: 改配置`（太模糊）
`ci`	CI 配置变更	`ci: 调整 GitHub Actions 缓存策略`	`ci: 修ci`（不正式）
`chore`	杂项（不影响 src 和测试）	`chore: 更新依赖版本`	`chore: 做点杂活`（无意义）
`revert`	回滚提交	`revert: 回滚 feat: 添加暗黑模式`	`revert: 撤销上一个`（没说明撤销了什么）

常见扩展 Type

Type	含义
`init`	项目初始化
`release`	发布版本
`deprecate`	弃用某功能
`remove`	移除功能
`security`	安全修复
`i18n`	国际化/本地化

3. Scope（作用域）

Scope 用英文小写，多个单词用 - 连接，表示变更影响的模块。

常见 Scope 示例

Scope	对应模块
`api`	API 接口层
`auth`	认证/授权
`db`	数据库
`ui`	前端 UI
`worker`	后台任务
`config`	配置
`deps`	依赖
`types`	类型定义
`docs`	文档
`test`	测试

示例

PLAINTEXT

feat(auth): 添加 JWT 刷新机制
fix(api): 修复分页参数校验问题
docs(readme): 补充环境变量说明
refactor(order): 重构订单状态机
perf(db): 优化慢查询索引

4. Description（描述）

规则：

祈使句（现在时），不用过去时
首字母小写（中文直接写）
结尾不加句号
≤50 字符（中文 ≤30 字）

正确：

PLAINTEXT

feat: 添加用户注册功能
fix: 修复空指针异常

错误：

PLAINTEXT

feat: 添加了用户注册功能。    # 过去时 + 句号
Fix: 修复空指针异常           # 首字母大写
feat: 添加了用户注册功能并且修复了一个小bug并更新了文档  # 一条 commit 做多件事

5. Body（正文）

变更复杂时，空一行后写正文，说明：

为什么做这个变更
怎么实现的
有什么影响面

PLAINTEXT

feat(user): 支持手机号验证码登录

新增手机号登录方式，提升用户注册转化率。
实现了验证码发送、校验和登录频率限制（1分钟1次）。
补充相关单元测试和接口文档。

6. Footer（页脚）

关联 Issue

PLAINTEXT

Closes #123
Fixes #456
Refs #789

破坏性变更（Breaking Change）

方式一：Footer 声明

PLAINTEXT

BREAKING CHANGE: 登录接口返回结构从对象改为数组

方式二：Type 后加 !

PLAINTEXT

feat!: 重构用户认证接口

BREAKING CHANGE: 原 /login 接口已废弃，请使用 /auth/login

7. 完整示例

简单提交

PLAINTEXT

feat: 添加暗黑模式切换

带 Scope

PLAINTEXT

fix(api): 修复订单列表分页参数校验

完整结构

PLAINTEXT

feat(auth): 支持手机号验证码登录

新增手机号登录方式，提升用户注册转化率。
实现了验证码发送、校验和登录频率限制。

Closes #128

破坏性变更

PLAINTEXT

feat(api)!: 重构用户信息返回结构

将用户信息中的 avatar_url 字段重命名为 avatar。

BREAKING CHANGE: 前端需要同步修改字段名

常见违规示例

❌ 错误	✅ 正确	问题
`update`	`feat` 或 `fix`	用了非标准 type
`feat: 修了个 bug`	`fix: 修复空指针异常`	type 和描述矛盾
`feat: 添加登录功能 & 修复UI问题`	拆成两个 commit	一条 commit 做多件事
`fix(api,ui,db): 多个模块`	`fix(api): 只改一个模块`	scope 多个模块
`feat(home): 修改了很多东西`	`feat(home): 添加首页推荐算法`	描述太模糊
`feat: 接口修改`	`feat(api): 统一错误响应格式`	无 scope + 描述不清

8. 最佳实践

一次提交只做一件事
- ✅ fix: 修复支付金额计算错误
- ❌ feat: 添加登录功能并修复支付bug并更新文档
先写 description，再补充 body
- description 让人一眼看懂
- body 让人深入理解
团队统一 scope 命名
- 提前约定 scope 清单（如 api/auth/db/ui）
- scope 避免含义重叠
中英混写建议
- type + scope 用英文
- description + body 用中文（国内团队）
关联 Issue 不要忘
- Closes #123 会自动关闭 Issue
- Refs #456 用于部分关联
破坏性变更提前沟通
- 用 ! 醒目
- footer 写清楚迁移方案

9. 工具配置

commitlint（提交信息校验）

安装：

BASH

# 安装 commitlint + conventional 配置
npm install --save-dev @commitlint/cli @commitlint/config-conventional

# commitlint.config.js
echo "module.exports = { extends: ['@commitlint/config-conventional'] }" > commitlint.config.js

husky（Git hooks）

BASH

# 安装 husky
npm install --save-dev husky
npx husky init

# 添加 commit-msg hook
echo 'npx --no -- commitlint --edit $1' > .husky/commit-msg

安装后，每次 git commit 会自动校验提交信息格式，不合规范会拒绝提交。

Commitizen（交互式提交）

BASH

# 全局安装
npm install -g commitizen

# 项目初始化 cz-conventional-changelog
commitizen init cz-conventional-changelog --save-dev --save-exact

# 之后用 cz 代替 git commit
git cz

Commitizen 会弹出交互式表单，一步步选择 type、scope、写描述，避免格式错误。

Git alias（快捷方式）

BASH

# 配置别名
git config --global alias.co 'commit -m'
git config --global alias.cm 'commit -m'
git config --global alias.ca 'commit -a -m'

# 使用
git co "feat: 添加用户注册功能"

10. CI 自动化

semantic-release（自动版本号 + Changelog）

配置 .releaserc.json：

JSON

{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/github"
  ]
}

在 GitHub Actions 中：

YAML

name: Release
on:
  push:
    branches: [main]
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npx semantic-release

版本影响对照

提交类型	版本影响
`fix`	PATCH (1.0.x)
`feat`	MINOR (1.x.0)
带 `BREAKING CHANGE`	MAJOR (x.0.0)

11. FAQ

Q: 不小心写了错误的 type，怎么补救？
A: git commit --amend 修改上次提交信息。已推送远程则 git push --force-with-lease（谨慎使用）。

Q: body 太长了怎么换行？
A: git commit（不加 -m）会打开编辑器，直接写多行。body 每行建议 ≤72 字符。

Q: scope 选什么？
A: 按文件所在目录 / 功能模块 / 影响范围选。不确定时不写 scope 也比写错好。

Q: type 不够用怎么办？
A: 可以自定义，但需团队约定并在 commitlint 的 rules.type-enum 中注册。

Q: 纯前端/后端项目能用同一套规范吗？
A: 可以，scope 区分即可。前端用 feat(ui)，后端用 feat(api)。

Q: 如何查看已提交信息是否规范？
A: git log --oneline 快速浏览。或用 commitlint 的 CI 检查历史：npx commitlint --from HEAD~5。

Q: 用了 git cz 还要 commitlint 吗？
A: 同时用效果最佳——git cz 防格式错误，commitlint 防漏网之鱼（如 CI 中直接提交）。

12. 总原则

一条好的提交信息，让人不看代码也能理解：

做了什么（type + description）
影响哪里（scope）
为什么做（body）
有没有破坏兼容性（footer）

统一规范后，项目历史清晰、自动化工具生效、协作效率提升。

十七天天开心

生活明朗，万物可爱

本文是原创文章，采用 CC BY-NC-SA 4.0 协议，完整转载请注明来自十七天天开心

隐私政策

评论内容

0/500

昵称

邮箱

网址

滚动到此处加载评论...

安知鱼

来自安知鱼最新设计与科技的文章

查看全部

文章详情

互动

Git 约定式提交规范

268214分钟2026-08-1618未知0

Conventional Commits（约定式提交）

规范地址：https://www.conventionalcommits.org/

快速参考

场景	命令
新功能	`feat: 添加用户注册功能`
修 Bug	`fix: 修复空指针异常`
改文档	`docs: 更新 README 安装说明`
重构	`refactor: 提取公共工具函数`
性能优化	`perf: 优化列表渲染性能`
格式调整	`style: 统一代码缩进`
加测试	`test: 增加登录模块单元测试`
构建变更	`build: 升级 webpack 到 5.x`
CI 变更	`ci: 调整 GitHub Actions 流程`
杂项	`chore: 更新依赖版本`
回滚	`revert: 回滚添加暗黑模式`
带 Scope	`feat(auth): 支持手机号验证码登录`
破坏性变更	`feat!: 重构用户认证接口`
关联 Issue	`feat: 支持手机号登录\n\nCloses #128`

1. 格式

PLAINTEXT

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

部分	必填	说明
type	是	变更性质
scope	否	影响模块（小写英文，`-` 连接）
description	是	简短描述（祈使句，首字母小写，不加句号，≤50 字符）
body	否	详细说明（动机、实现方式、影响）
footer	否	关联 Issue、破坏性变更声明

2. Type 清单

Type	含义	好例子	坏例子
`feat`	新增功能	`feat: 支持微信登录`	`feat: 添加了订单功能。`（过去时+句号）
`fix`	修复 Bug	`fix: 修复支付金额计算错误`	`Fix: 修复空指针`（首字母大写）
`docs`	文档变更	`docs: 更新 README 安装说明`	`docs: 修改readme`（描述不够明确）
`style`	格式调整（不影响逻辑）	`style: 统一代码缩进为2空格`	`style: 改了个格式`（没说明改了啥）
`refactor`	重构（非功能非修复）	`refactor: 提取公共工具函数`	`refactor: 重写一大堆`（太模糊）
`perf`	性能优化	`perf: 优化列表虚拟滚动渲染`	`perf: 快了`（无量化描述）
`test`	测试相关	`test: 增加登录模块单元测试`	`test: 加测试`（没说明测什么）
`build`	构建系统/外部依赖变更	`build: 升级 webpack 到 5.x`	`build: 改配置`（太模糊）
`ci`	CI 配置变更	`ci: 调整 GitHub Actions 缓存策略`	`ci: 修ci`（不正式）
`chore`	杂项（不影响 src 和测试）	`chore: 更新依赖版本`	`chore: 做点杂活`（无意义）
`revert`	回滚提交	`revert: 回滚 feat: 添加暗黑模式`	`revert: 撤销上一个`（没说明撤销了什么）

常见扩展 Type

Type	含义
`init`	项目初始化
`release`	发布版本
`deprecate`	弃用某功能
`remove`	移除功能
`security`	安全修复
`i18n`	国际化/本地化

3. Scope（作用域）

Scope 用英文小写，多个单词用 - 连接，表示变更影响的模块。

常见 Scope 示例

Scope	对应模块
`api`	API 接口层
`auth`	认证/授权
`db`	数据库
`ui`	前端 UI
`worker`	后台任务
`config`	配置
`deps`	依赖
`types`	类型定义
`docs`	文档
`test`	测试

示例

PLAINTEXT

feat(auth): 添加 JWT 刷新机制
fix(api): 修复分页参数校验问题
docs(readme): 补充环境变量说明
refactor(order): 重构订单状态机
perf(db): 优化慢查询索引

4. Description（描述）

规则：

祈使句（现在时），不用过去时
首字母小写（中文直接写）
结尾不加句号
≤50 字符（中文 ≤30 字）

正确：

PLAINTEXT

feat: 添加用户注册功能
fix: 修复空指针异常

错误：

PLAINTEXT

feat: 添加了用户注册功能。    # 过去时 + 句号
Fix: 修复空指针异常           # 首字母大写
feat: 添加了用户注册功能并且修复了一个小bug并更新了文档  # 一条 commit 做多件事

5. Body（正文）

变更复杂时，空一行后写正文，说明：

为什么做这个变更
怎么实现的
有什么影响面

PLAINTEXT

feat(user): 支持手机号验证码登录

新增手机号登录方式，提升用户注册转化率。
实现了验证码发送、校验和登录频率限制（1分钟1次）。
补充相关单元测试和接口文档。

6. Footer（页脚）

关联 Issue

PLAINTEXT

Closes #123
Fixes #456
Refs #789

破坏性变更（Breaking Change）

方式一：Footer 声明

PLAINTEXT

BREAKING CHANGE: 登录接口返回结构从对象改为数组

方式二：Type 后加 !

PLAINTEXT

feat!: 重构用户认证接口

BREAKING CHANGE: 原 /login 接口已废弃，请使用 /auth/login

7. 完整示例

简单提交

PLAINTEXT

feat: 添加暗黑模式切换

带 Scope

PLAINTEXT

fix(api): 修复订单列表分页参数校验

完整结构

PLAINTEXT

feat(auth): 支持手机号验证码登录

新增手机号登录方式，提升用户注册转化率。
实现了验证码发送、校验和登录频率限制。

Closes #128

破坏性变更

PLAINTEXT

feat(api)!: 重构用户信息返回结构

将用户信息中的 avatar_url 字段重命名为 avatar。

BREAKING CHANGE: 前端需要同步修改字段名

常见违规示例

❌ 错误	✅ 正确	问题
`update`	`feat` 或 `fix`	用了非标准 type
`feat: 修了个 bug`	`fix: 修复空指针异常`	type 和描述矛盾
`feat: 添加登录功能 & 修复UI问题`	拆成两个 commit	一条 commit 做多件事
`fix(api,ui,db): 多个模块`	`fix(api): 只改一个模块`	scope 多个模块
`feat(home): 修改了很多东西`	`feat(home): 添加首页推荐算法`	描述太模糊
`feat: 接口修改`	`feat(api): 统一错误响应格式`	无 scope + 描述不清

8. 最佳实践

一次提交只做一件事
- ✅ fix: 修复支付金额计算错误
- ❌ feat: 添加登录功能并修复支付bug并更新文档
先写 description，再补充 body
- description 让人一眼看懂
- body 让人深入理解
团队统一 scope 命名
- 提前约定 scope 清单（如 api/auth/db/ui）
- scope 避免含义重叠
中英混写建议
- type + scope 用英文
- description + body 用中文（国内团队）
关联 Issue 不要忘
- Closes #123 会自动关闭 Issue
- Refs #456 用于部分关联
破坏性变更提前沟通
- 用 ! 醒目
- footer 写清楚迁移方案

9. 工具配置

commitlint（提交信息校验）

安装：

BASH

# 安装 commitlint + conventional 配置
npm install --save-dev @commitlint/cli @commitlint/config-conventional

# commitlint.config.js
echo "module.exports = { extends: ['@commitlint/config-conventional'] }" > commitlint.config.js

husky（Git hooks）

BASH

# 安装 husky
npm install --save-dev husky
npx husky init

# 添加 commit-msg hook
echo 'npx --no -- commitlint --edit $1' > .husky/commit-msg

安装后，每次 git commit 会自动校验提交信息格式，不合规范会拒绝提交。

Commitizen（交互式提交）

BASH

# 全局安装
npm install -g commitizen

# 项目初始化 cz-conventional-changelog
commitizen init cz-conventional-changelog --save-dev --save-exact

# 之后用 cz 代替 git commit
git cz

Commitizen 会弹出交互式表单，一步步选择 type、scope、写描述，避免格式错误。

Git alias（快捷方式）

BASH

# 配置别名
git config --global alias.co 'commit -m'
git config --global alias.cm 'commit -m'
git config --global alias.ca 'commit -a -m'

# 使用
git co "feat: 添加用户注册功能"

10. CI 自动化

semantic-release（自动版本号 + Changelog）

配置 .releaserc.json：

JSON

{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/github"
  ]
}

在 GitHub Actions 中：

YAML

name: Release
on:
  push:
    branches: [main]
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npx semantic-release

版本影响对照

提交类型	版本影响
`fix`	PATCH (1.0.x)
`feat`	MINOR (1.x.0)
带 `BREAKING CHANGE`	MAJOR (x.0.0)

11. FAQ

Q: 不小心写了错误的 type，怎么补救？
A: git commit --amend 修改上次提交信息。已推送远程则 git push --force-with-lease（谨慎使用）。

Q: body 太长了怎么换行？
A: git commit（不加 -m）会打开编辑器，直接写多行。body 每行建议 ≤72 字符。

Q: scope 选什么？
A: 按文件所在目录 / 功能模块 / 影响范围选。不确定时不写 scope 也比写错好。

Q: type 不够用怎么办？
A: 可以自定义，但需团队约定并在 commitlint 的 rules.type-enum 中注册。

Q: 纯前端/后端项目能用同一套规范吗？
A: 可以，scope 区分即可。前端用 feat(ui)，后端用 feat(api)。

Q: 如何查看已提交信息是否规范？
A: git log --oneline 快速浏览。或用 commitlint 的 CI 检查历史：npx commitlint --from HEAD~5。

Q: 用了 git cz 还要 commitlint 吗？
A: 同时用效果最佳——git cz 防格式错误，commitlint 防漏网之鱼（如 CI 中直接提交）。

12. 总原则

一条好的提交信息，让人不看代码也能理解：

做了什么（type + description）
影响哪里（scope）
为什么做（body）
有没有破坏兼容性（footer）

统一规范后，项目历史清晰、自动化工具生效、协作效率提升。

十七天天开心

生活明朗，万物可爱

本文是原创文章，采用 CC BY-NC-SA 4.0 协议，完整转载请注明来自十七天天开心

隐私政策

评论内容

0/500

昵称

邮箱

网址

滚动到此处加载评论...

安知鱼

来自安知鱼最新设计与科技的文章

查看全部