手把手教你定制Vue3项目的Git提交规范：cz-customizable实战

🎓 作者简介 ： 前端领域优质创作者

🚪 资源导航： 传送门=>

🎬 个人主页： 江城开朗的豌豆

🌐 个人网站: 江城开朗的豌豆 🌍

📧 个人邮箱: [email protected] 📩

💬 个人微信: y_t_t_t_ 📱

📌 座右铭: 生活就像心电图，一帆风顺就证明你挂了。 💔

👥 QQ群: 906392632 (前端技术交流群) 💬

前言：为什么我们需要规范提交信息？

最近团队新来的实习生小杨遇到了一个头疼的问题：查看项目历史提交记录时，发现有的同事用中文写提交信息，有的用英文；有的写"修改bug"，有的写"修复问题"。这种混乱导致回溯代码变更时效率极低，于是我们决定引入cz-customizable来统一提交规范。

一、基础环境搭建

1.1 创建示例项目（已有项目可跳过）

bash 复制代码

npm create vue@latest cz-customizable-demo

1.2 安装核心依赖

bash 复制代码

cd cz-customizable-demo
npm install commitizen cz-customizable -D

二、配置文件详解

2.1 创建配置文件

在项目根目录新建.cz-config.js文件：

javascript 复制代码

/*
 * @Author: 杨涛
 * @Description:代码提交规范
 * @Date: 2022-12-07 21:02:13
 * @LastEditTime: 2022-12-08 20:32:50
 * @FilePath: \text\.cz-config.js
 */
module.exports = {
  types: [
    { value: '🚀 新增  ', name: '新增:  新的内容' },
    { value: '🐛 修复  ', name: '修复:  修复一个Bug' },
    { value: '📝 文档  ', name: '文档:  变更的只有文档' },
    { value: '🏠 格式  ', name: '格式:  空格, 分号等格式修复' },
    { value: '♻️ 重构  ', name: '重构:  代码重构，注意和特性、修复区分开' },
    { value: '⚡️ 性能  ', name: '性能:  提升性能' },
    { value: '✅ 测试  ', name: '测试:  添加一个测试' },
    { value: '🔨 工具  ', name: '工具:  开发工具变动(构建、脚手架工具等)' },
    { value: '⏪ 回滚  ', name: '回滚:  代码回退' },
  ],
 
  // Specify the scopes for your particular project
  scopes: [],
  messages: {
    type: '选择一种你的提交类型: \n',
    cope: '选择一个 scope（可选）\n：',
    customScope: '请输入修改范围(可选): \n',
    subject: '短说明: \n',
    body: '长说明，使用 "|" 换行(可选)：\n',
    breaking: '非兼容性说明 (可选): \n',
    footer: '关联关闭的issue，例如：#31, #34(可选): \n',
    confirmCommit: '确定提交说明? \n',
  },
  // 跳过空的 scope
  skipEmptyScopes: true,
  skipQuestions: ['scopes', 'breaking', 'body', 'footer'],
  // 设置为 true，在 scope 选择的时候，会有 empty 和 custom 可以选择
  // 顾名思义，选择 empty 表示 scope 缺省，如果选择 custom，则可以自己输入信息
  allowCustomScopes: true,
  // 只有我们 type 选择了 feat 或者是 fix，才会询问我们 breaking message.
  allowBreakingChanges: ['feat', 'fix'],
    subjectLimit: 72
};

2.2 修改package.json

json 复制代码

{
  "config": {
    "commitizen": {
      "path": "node_modules/cz-customizable"
    }
  },
  "scripts": {
    "commit": "git add . && git-cz"
  }
}

三、适配Vue3项目特性

3.1 处理组合式API提交

对于<script setup>的单文件组件，建议在提交信息中标注：

javascript 复制代码

// .cz-config.js
module.exports = {
  // ...其他配置
  scopes: [
    'components',
    'composables',
    'views',
    'styles',
    'router',
    'store'
  ]
};

3.2 提交示例演示

bash 复制代码

npm run commit

按提示操作：

bash 复制代码

? 请选择提交类型： feat
? 请简要描述提交（必填）： 新增用户登录组件
? 请输入详细描述（可选）： 
- 实现手机号+验证码登录
- 添加图形验证码功能
? 请输入关联ISSUE（可选）： #123

生成规范的提交信息：

复制

markdown 复制代码

feat(components): 新增用户登录组件

- 实现手机号+验证码登录
- 添加图形验证码功能

#123

四、高级定制技巧

4.1 自动关联Jira任务

javascript 复制代码

// .cz-config.js
module.exports = {
  allowTicketNumber: true,
  isTicketNumberRequired: true,
  ticketNumberPrefix: 'JIRA-',
  ticketNumberRegExp: '\d{1,5}'
};

4.2 团队规范校验

安装校验工具：

bash 复制代码

npm install @commitlint/cli @commitlint/config-conventional -D

创建commitlint.config.js：

javascript 复制代码

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'feat', 'fix', 'docs', 'style', 'refactor', 
      'perf', 'test', 'chore'
    ]],
    'subject-case': [0]
  }
};

五、常见问题解决方案

5.1 中文乱码问题

在.gitconfig中添加：

ini 复制代码

[gui]
  encoding = utf-8
[i18n]
  commitEncoding = utf-8

5.2 与Husky集成

安装Husky：

bash 复制代码

npm install husky -D
npx husky install
npx husky add .husky/commit-msg 'npx commitlint --edit "$1"'

六、可视化提交记录

安装分析工具：

bash 复制代码

npm install conventional-changelog-cli -D

生成CHANGELOG：

json 复制代码

{
  "scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
  }
}

执行生成：

bash 复制代码

npm run changelog

结语：规范带来的改变

自从小杨推动团队使用cz-customizable后，我们的提交日志变得清晰可读。结合自动生成的CHANGELOG，版本发布效率提升了40%。更重要的是，当新人接手项目时，通过规范的提交信息能快速理解代码演进过程。

最后的小技巧 ：在.vscode/settings.json中添加以下配置，可以获得提交类型提示：

json 复制代码

{
  "git.inputValidationSubjectLength": 72
}