主流 Git Commit 规范：约定式提交 (Conventional Commits)

约定式提交的格式非常简洁，结构如下：

1
2
3
4
5
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

对于大部分提交来说，通常只需要第一行（header）就足够了。

1. Header

Header 部分只有一行，包括三个字段：type（必需）、scope（可选）和 subject（必需）。

Type (类型)

type 用于说明 commit 的类别，只允许使用下面几个标识：

Type 描述
feat 新功能 (feature)
fix 修复 Bug
docs 文档 (documentation)
style 格式 (不影响代码运行的变动，例如空格、格式化、缺少分号等)
refactor 重构 (既不是新增功能，也不是修改 bug 的代码变动)
perf 性能优化 (提升性能的代码更改)
test 测试 (增加或修改测试)
chore 构建过程或辅助工具的变动 (例如修改 vite.config.ts、package.json等)
revert 回滚 (如果当前 commit 用于撤销之前的 commit)

Scope (范围) - 可选

scope 用于说明 commit 影响的范围，比如数据层、控制层、视图层等等，视项目不同而不同。在我的这个项目中，可以是：

  • stores: 修改了 zustand 的 store
  • hooks: 修改了自定义 Hook
  • setting: 修改了右侧设置面板
  • materials: 修改或新增了物料组件
  • dnd: Drag and Drop (拖放) 相关逻辑
  • deps: 依赖项更新

Subject (主题)

subject 是 commit 目的的简短描述，不超过50个字符，结尾不加句号（.）。

2. Body (正文) - 可选

body 部分是对本次 commit 的详细描述，可以分成多行。应该说明代码变动的动机，以及与以前行为的对比。

footer 部分只用于两种情况：

  • 不兼容变动 (Breaking Change): 以 BREAKING CHANGE: 开头，后面是变动描述。
  • 关闭 Issue: Closes #123, Closes #456

针对我项目的提交示例

现在，把我最近做的事情用约定式提交来表示一下：

  • 为我添加注释后

    Bash

    1
    git commit -m "docs(stores):为 component-config 和 components 两个 store 添加 JSDoc 注释"
    • type: docs，因为只是添加文档/注释。
    • scope: stores，因为修改的是 store 文件。
    • subject: 清晰说明了做了什么。

  • 修复了拖拽物料到表格中，高亮边框不显示的 bug

    Bash

    1
    git commit -m "fix(materials): 修复 TableDev 组件在拖拽悬停时 canDrop 样式未生效的问题"
    • type: fix
    • scope: materials (或 dnd)
    • subject: 描述修复的具体问题。

  • 为 Button 组件增加一个新的“幽灵按钮”类型

    Bash

    1
    git commit -m "feat(materials): 为 Button 组件增加 ghost 类型" -m "新的 ghost 按钮类型允许在有色背景上使用，增加了设计的灵活性。同时更新了 component-config 中的 setter 选项。"
    • type: feat
    • body: (可选) 详细说明了变动的动机和内容。

如何在项目中落地？

要保证团队成员都遵循规范，可以引入工具来自动化检查。

  1. Commitizen: 一个命令行工具，可以交互式地引导我创建符合规范的 commit message。
  2. Husky: 可以让我在 git commit 或 git push 等钩子（hooks）上运行脚本。
  3. commitlint: 配合 Husky 使用，在 commit-msg 钩子上检查我的 commit message 是否符合规范。

虽然我的 package.json 里现在没有这些工具，但在项目发展到一定阶段时，引入它们会是一个非常好的实践。