前端Git协作“规范化提交“工具包

本文最后更新于239 天前，如有错误请发送邮件到yaoshengliy@gmail.com

前言

在日常的团队协作开发中，良好的 Git 提交规范不仅能够提高代码的可维护性、审查效率，还能为自动化部署、变更日志生成等提供坚实基础。为了更便捷地执行规范化提交，我们封装了一个 Git 提交规范工具包，通过 Commitizen、Commitlint、Husky 等工具，帮助开发者轻松约束和统一提交行为。

注：本文介绍的Git规范化提交工具包为1.0版本，较为简单，适配小团队需求。

协作规范化提交说明

在进行安装工具包之前，需要了解Git中commit规范化格式。本文参照Angular规范进行说明。

常见提交类型（type）

类型	描述
feat	✨ 新增功能
fix	🐛 修复Bug
docs	📝 文档修改
style	💄 代码格式（不影响逻辑）
refactor	♻️ 代码重构（非新增或修复）
perf	⚡ 性能优化
test	✅ 添加或修改测试代码
build	🔧 构建系统或依赖修改
ci	👷 持续集成配置
chore	🧹 杂项（构建/脚手架等）
revert	⏪ 回退某次提交

影响范围（scope）示例

例如以下模块或目录名称，可作为 scope(一般不用，因为提交已经知道修改了哪里)：

user
login
order
api
ui
config

# 示例提交
feat(login): 添加验证码登录功能
fix(api): 修复接口数据返回异常问题
docs(readme): 完善项目启动说明
style(ui): 调整按钮样式
refactor(user): 重构用户信息模块

简要描述、详细描述

简要描述（summary）：一句简短的话说明更改的内容。

详细描述（body，可选）：对提交信息进行详细描述，可选。通常包括重要文件说明，重点更改，注意事项等等。

footer（页脚）

Footer 类型	写法示例	说明	是否自动触发平台动作
关联 Issue（关闭）	Closes #123	表示此提交将关闭编号为 #123 的 Issue	✅ GitHub/GitLab 等
关联 Issue（修复）	Fixes #45	表示此提交修复了 Issue #45	✅ GitHub/GitLab 等
兼容性变更	BREAKING CHANGE: 改动描述	表示该提交包含重大不兼容的更改（如删除旧功能）	✅ semantic-release 等
多个 Issue 一起关闭	Closes #12, Fixes #34	一个提交关联多个 Issue	✅
普通备注说明	Related to #78	表示这个提交与 Issue #78 有关，但不自动关闭它	❌

# 示例提交
feat(auth): 支持二维码登录

实现用户通过微信扫码登录功能，兼容移动端

Closes #101
BREAKING CHANGE: 登录逻辑修改，老版本用户需重新登录

Closes #id / Fixes #id：自动关闭 Issue（Pull Request 合并后）
BREAKING CHANGE:：告知有重大变更，适用于版本发布自动化工具（如 semantic-release）

由上述已对Git规范化提交进行了简要说明，接下来进行工具包的安装。

工具包简介

前端环境

工具 / 框架	推荐版本	说明
Node.js	>=14.0.0	最低 Node 14 支持 ES 模块配置和 Husky v7+ 等现代工具运行。建议使用 LTS（如 Node 18/20）。
npm	>=6.0.0	支持 `npx` 和自动执行 scripts。Node 安装时自带。
Git	>=2.30.0	确保 Git 支持 `hook` 执行，便于 Husky 使用。
Vue.js	Vue 2.x 或 Vue 3.x	本工具包Vue2与Vue3的初始化有细微差别，将在下文分别指出。
Package Manager	npm / pnpm / yarn	推荐使用 `npm`，因为脚本中用到了 `npx`。如使用其他工具，请手动调整命令。

工具包依赖版本

工具名	版本范围（建议）	说明
`commitizen`	^4.3.0	生成规范提交的交互式 CLI 工具
`cz-customizable`	^6.9.0	可配置 Commitizen 的交互字段（使用最新版也可以）
`@commitlint/cli`	^17.4.0	校验提交信息格式的核心工具
`@commitlint/config-conventional`	^17.4.0	使用 Angular 提交规范作为默认规则
`husky`	^8.0.0	管理 Git hooks，例如 commit-msg hook

对应前端环境，建议开发者适配；对于工具包依赖，则在下文提供脚本一建初始化。

使用步骤

我们将所有配置封装为一个初始化脚本，开发者只需执行一次初始化，即可在项目中启用 Git 提交规范。同时需要注意，脚本文件以.sh结尾，则需要在Linux/macOS操作系统进行初始化。

Windows操作系统的开发者，使用Git bash环境即可初始化脚本（Git bash提供Linux环境）。

初始化脚本之前，请确保前端项目已经运行成功（保证相关配置文件存在，如package.json）。下述是使用步骤：

步骤 1： 在项目根目录导入初始化脚本文件init-git-commit.sh(不同Vue版本使用脚本不同，脚本内容在下文)，之后在项目根目录打开Git bash命令行执行 ./init-git-commit.sh
步骤 2： 将所需提交的文件放置暂存区，使用 npm run commit 运行命令，程序会按照上述Angular规则与开发者进行交互
步骤 3： 提交信息将经过自动校验，不符合规则会被阻止

初始化成功后，使用npm run commit命令测试程序是否正常运行。

初始化脚本成功示例图：

程序运行成功示例图：

将指定文件放置暂存区后，程序运行示例图：

运行程序相关命令介绍（type类型可以用键盘上下键选择，回车即可确认）：

初始化脚本（Linux/macOS）

Vue2

#!/bin/bash

echo "📦 正在安装依赖..."
npm install --save-dev commitizen cz-customizable @commitlint/cli @commitlint/config-conventional husky

echo "📦 安装 json 命令行工具..."
npm install -g json

echo "🛠️ 正在初始化配置文件..."

# commitlint.config.js
cat <<EOF > commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat',
        'fix',
        'docs',
        'style',
        'refactor',
        'perf',
        'test',
        'build',
        'ci',
        'chore',
        'revert'
      ]
    ]
  }
};
EOF

# .cz-config.js
cat <<EOF > .cz-config.js
'use strict';

module.exports = {
  types: [
    { value: 'feat',     name: 'feat:     新功能' },
    { value: 'fix',      name: 'fix:      修复Bug' },
    { value: 'docs',     name: 'docs:     文档变更' },
    { value: 'style',    name: 'style:    代码格式（不影响逻辑）' },
    { value: 'refactor', name: 'refactor: 代码重构（不新增功能、不修复bug）' },
    { value: 'perf',     name: 'perf:     性能优化' },
    { value: 'test',     name: 'test:     增加测试' },
    { value: 'build',    name: 'build:    构建相关' },
    { value: 'ci',       name: 'ci:       持续集成配置' },
    { value: 'chore',    name: 'chore:    其他修改（构建、脚手架等）' },
    { value: 'revert',   name: 'revert:   回退提交' }
  ],
  messages: {
    type: "选择你要提交的类型:",
    scope: "填写影响范围（可选）:",
    subject: "简短描述（不超过50字）:",
    body: "详细描述（可选，使用'|'换行）:",
    footer: "相关 issue（可选）:",
    confirmCommit: "确认提交？"
  }
};
EOF

echo "🔧 正在更新 package.json 中的 commitizen 配置..."

npx json -I -f package.json -e '
this.scripts = this.scripts || {};
this.scripts.commit = "cz";
this.config = this.config || {};
this.config.commitizen = { "path": "./.cz-config.js" };
'

echo "🐶 正在初始化 Husky..."
npx husky install
npx husky add .husky/commit-msg "npx --no -- commitlint --edit \$1"

echo "✅ 初始化完成！🎉 现在你可以使用：npm run commit 来规范化 Git 提交"

Vue3

#!/bin/bash

echo "📦 安装依赖中..."
npm install --save-dev commitizen cz-customizable @commitlint/cli @commitlint/config-conventional husky

echo "📦 安装 json 命令行工具..."
npm install -g json

echo "🛠️ 创建 commitlint.config.js..."
cat <<EOF > commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat',
        'fix',
        'docs',
        'style',
        'refactor',
        'perf',
        'test',
        'build',
        'ci',
        'chore',
        'revert'
      ]
    ]
  }
};
EOF

echo "🛠️ 创建 .cz-config.cjs..."
cat <<EOF > .cz-config.cjs
'use strict';

module.exports = {
  types: [
    { value: 'feat',     name: 'feat:     新功能' },
    { value: 'fix',      name: 'fix:      修复Bug' },
    { value: 'docs',     name: 'docs:     文档变更' },
    { value: 'style',    name: 'style:    代码格式（不影响逻辑）' },
    { value: 'refactor', name: 'refactor: 代码重构（不新增功能、不修复bug）' },
    { value: 'perf',     name: 'perf:     性能优化' },
    { value: 'test',     name: 'test:     增加测试' },
    { value: 'build',    name: 'build:    构建相关' },
    { value: 'ci',       name: 'ci:       持续集成配置' },
    { value: 'chore',    name: 'chore:    其他修改（构建、脚手架等）' },
    { value: 'revert',   name: 'revert:   回退提交' }
  ],
  messages: {
    type: "选择你要提交的类型:",
    scope: "填写影响范围（可选）:",
    subject: "简短描述（不超过50字）:",
    body: "详细描述（可选，使用'|'换行）:",
    footer: "相关 issue（可选）:",
    confirmCommit: "确认提交？"
  },
  allowCustomScopes: true,
  allowBreakingChanges: ['feat', 'fix']
};
EOF

echo "🔧 修改 package.json..."
npx json -I -f package.json -e '
this.scripts = this.scripts || {};
this.scripts.commit = "cz";

this.config = this.config || {};
this.config.commitizen = { path: "./.cz-config.cjs" };
'

echo "🐶 初始化 husky..."
npx husky install
npx husky add .husky/commit-msg "npx --no -- commitlint --edit \$1"

echo "✅ 初始化完成！🎉 现在你可以使用：npm run commit 来规范化 Git 提交"

常见问题

提示找不到 .cz-config.js？请确保路径正确或将其改为 .cz-config.cjs。
无法输入中文？请检查终端编码，建议使用 VSCode 的 Git Bash 或 PowerShell。

结语

通过这套工具包的简单示例，团队成员可以更专注于开发而无需记忆复杂的提交规范，开发者也可以在此工具包的基础上进行改进完善。我们鼓励每一个项目从一开始就引入 Git 提交规范，让协作更高效、历史记录更清晰。

前言