语义化提交规范如何应用

本文目录导读：

1. 核心格式
2. 关键要素详解
3. 完整示例
4. 如何应用到实际工作流
5. 常见问题与最佳实践

语义化提交规范（通常指Conventional Commits）是一种约定，用于格式化 Git 提交信息，它的核心价值在于让提交历史可读、可追溯、可自动化（比如自动生成 changelog 和自动触发版本发布）。

下面我为你详细讲解如何在实际项目中应用这套规范。

核心格式

一条标准的语义化提交信息由三部分组成：Header（头部）、Body（正文） 和 Footer（页脚）。

<类型>(<可选范围>): <简短描述>
<可选页脚>

最重要的部分是 Header，它只有一行，类型 和 之间有一个空格。

关键要素详解

类型（Type）—— 最常用，必须写

这是规范的核心,决定了这次提交的性质。

• feat：新功能（feature）。feat: 添加用户登录模块
• fix：修复 bug。fix: 修复登录按钮点击无响应的问题
• docs：仅文档更改。docs: 更新 README 安装步骤
• style：不影响代码含义的更改（空格、格式化、缺少分号等）。style: 使用 Prettier 格式化全部代码。注意：不是 CSS 样式的更改。
• refactor：代码重构（既不修复错误也不添加功能）。refactor: 提取公共函数优化重复代码
• perf：提高性能的代码更改。perf: 使用缓存优化列表渲染速度
• test：添加或修改测试。test: 添加用户注册接口单元测试
• chore：构建过程或辅助工具的变动（升级依赖、修改 CI 配置）。chore: 升级 eslint 版本到 8.0
• ci：持续集成相关的更改。ci: 更新 GitHub Actions 部署脚本

范围（Scope）—— 可选

用于说明受影响的模块、文件或组件，用括号包裹。

• feat(cart): 添加商品数量加减功能
• fix(auth): 修复 token 过期后重定向死循环

简短描述（Subject）—— 必须写

• 用祈使句，添加”、“修复”、“删除”，而不是“已添加”、“已修复”。
• 首字母小写（英文场景）。
• 结尾不要加句号。
• 尽量控制在50个字符以内，最长不超过72个字符。

正文（Body）—— 可选

• 用于详细说明本次提交的动机、与之前行为的对比。
• 可以解释 为什么 要这么修改。

页脚（Footer）—— 可选

• 主要用于两种场景：
  • Breaking Changes（重大变更）：以 BREAKING CHANGE: 开头，后面跟上描述。
  • 关闭 Issue：引用一个或多个 Issue 编号，如 Closes #123, #456。

完整示例

# 1. 最普通的 feat（新功能）
feat: 用户模块增加头像上传功能
# 2. 带有范围的 fix（修复 bug）
fix(login): 修复验证码倒计时显示不正确
# 3. 带有正文的提交（解释“为什么”）
feat: 日志系统引入异步写入
由于高峰期日志写入 IO 阻塞严重，现改为内存队列+批量异步写入模式。
这会将写入延迟降低 80%，
# 4. 带有重大变更和关闭 Issue 的提交
feat!: 重构支付回调接口
BREAKING CHANGE: 将 payCallback 方法的参数从 order对象改为 orderId字符串。
Closes #88
# 5. 纯文档修改
docs: 修复 API 文档中关于分页参数的描述错误

如何应用到实际工作流

手动遵循

在 git commit -m "" 时，主动按照规范写，这是最基础的应用。

借助工具辅助

• Commitizen：一个交互式命令行工具，引导你填写规范信息。
  • 全局安装：npm install -g commitizen
  • 项目中初始化（使用 cz-conventional-changelog）：commitizen init cz-conventional-changelog --save-dev --save-exact
  • 之后用 git cz 代替 git commit。
• VSCode 插件：搜索 Conventional Commits 或 Commit Message Editor，可以在编辑器中可视化填写提交信息。

使用 Husky + commitlint 进行校验（推荐）

避免团队成员提交不符合规范的 commit。

• 安装 Husky：npx husky-init && npm install
• 安装 commitlint：npm install --save-dev @commitlint/config-conventional @commitlint/cli
• 配置（在根目录新建 commitlint.config.js）：

  module.exports = {
    extends: ['@commitlint/config-conventional']
  };

• 添加钩子：npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

这样,只要有人执行 git commit，如果提交信息不符合规范，commitlint 就会拒绝这次提交。

自动化生成 Changelog

配合 standard-version 或 semantic-release 工具，可以：

• 自动根据 feat, fix, BREAKING CHANGE 等标记分析版本号变化。
• 自动生成格式良好的 CHANGELOG.md 文件。
• 自动打 Git Tag。

常用命令：npx standard-version 或 npx semantic-release

常见问题与最佳实践

1. 别过度设计：不是所有提交都必须有范围（scope），对于小项目，feat: 和 fix: 就覆盖了 80% 的场景。
2. 保持原子性：一次提交只做一件事（一个 bug 修复，或一个独立功能），不要在一个 commit 里同时修复 bug 和添加功能。
3. 英文 vs 中文：国内团队大多使用中文描述，直观明了，没问题，英文场景则注意首字母小写。
4. 处理 WIP（Work In Progress）：如果开发中需要暂存，可以用 wip: ...，但合并前一定要清理为规范的 commit，或者使用 git rebase -i 合并压缩。
5. 团队约定：如果团队决定引入，建议在项目根目录放一个 CONTRIBUTING.md 或直接在 README 里写清楚规则，并配合上面的钩子自动检查，确保落地。

应用步骤：

1. 手动写规范：立即开始用 feat: 和 fix:。
2. 工具辅助：安装 Commitizen 或 VSCode 插件，降低输入成本。
3. 强制校验：添加 commitlint + husky 钩子，确保团队遵守。
4. 自动化：接入 standard-version 自动生成 Changelog 和版本号。

这套规范是行业最佳实践,上手后能显著提升项目协作效率和版本管理清晰度，建议现在就可以从第1步开始尝试。