🎓 作者简介： 前端领域优质创作者
🚪 资源导航： 传送门=>
🎬 个人主页： 江城开朗的豌豆
🌐 个人网站: 江城开朗的豌豆 🌍
📧 个人邮箱: YANG_TAO_WEB@163.com 📩
💬 个人微信: y_t_t_t_ 📱
📌 座 右 铭: 生活就像心电图，一帆风顺就证明你挂了。 💔
👥 QQ群: 906392632 (前端技术交流群) 💬
前言：为什么我们需要规范提交信息？
最近团队新来的实习生小杨遇到了一个头疼的问题：查看项目历史提交记录时，发现有的同事用中文写提交信息，有的用英文；有的写"修改bug"，有的写"修复问题"。这种混乱导致回溯代码变更时效率极低，于是我们决定引入cz-customizable来统一提交规范。
一、基础环境搭建
1.1 创建示例项目（已有项目可跳过）
npm create vue@latest cz-customizable-demo
1.2 安装核心依赖
cd cz-customizable-demo
npm install commitizen cz-customizable -D
二、配置文件详解
2.1 创建配置文件
在项目根目录新建.cz-config.js文件：
/*
* @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
{
"config": {
"commitizen": {
"path": "node_modules/cz-customizable"
}
},
"scripts": {
"commit": "git add . && git-cz"
}
}
三、适配Vue3项目特性
3.1 处理组合式API提交
对于<script setup>的单文件组件，建议在提交信息中标注：
// .cz-config.js
module.exports = {
// ...其他配置
scopes: [
'components',
'composables',
'views',
'styles',
'router',
'store'
]
};
3.2 提交示例演示
npm run commit
按提示操作：
? 请选择提交类型： feat
? 请简要描述提交（必填）： 新增用户登录组件
? 请输入详细描述（可选）：
- 实现手机号+验证码登录
- 添加图形验证码功能
? 请输入关联ISSUE（可选）： #123
生成规范的提交信息：
复制
feat(components): 新增用户登录组件
- 实现手机号+验证码登录
- 添加图形验证码功能
#123
四、高级定制技巧
4.1 自动关联Jira任务
// .cz-config.js
module.exports = {
allowTicketNumber: true,
isTicketNumberRequired: true,
ticketNumberPrefix: 'JIRA-',
ticketNumberRegExp: '\d{1,5}'
};
4.2 团队规范校验
安装校验工具：
npm install @commitlint/cli @commitlint/config-conventional -D
创建commitlint.config.js：
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中添加：
[gui]
encoding = utf-8
[i18n]
commitEncoding = utf-8
5.2 与Husky集成
安装Husky：
npm install husky -D
npx husky install
npx husky add .husky/commit-msg 'npx commitlint --edit "$1"'
六、可视化提交记录
安装分析工具：
npm install conventional-changelog-cli -D
生成CHANGELOG：
{
"scripts": {
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
}
}
执行生成：
npm run changelog
结语：规范带来的改变
自从小杨推动团队使用cz-customizable后，我们的提交日志变得清晰可读。结合自动生成的CHANGELOG，版本发布效率提升了40%。更重要的是，当新人接手项目时，通过规范的提交信息能快速理解代码演进过程。
最后的小技巧：在.vscode/settings.json中添加以下配置，可以获得提交类型提示：
{
"git.inputValidationSubjectLength": 72
}
