commitlint安装和配置使用教程

规范团队的commit提交规范，采用工具验证commit提交命令

本文包含了 commitlint 安装使用、commitizen适配器安装使用、中文适配器安装使用、自定义内容适配器安装使用以及遇到的几个问题

我采用的是pnpm命令安装，部分错误在文中给出了另外解决命令，npm、yarn命令需要用到在看是否有报错

commitlint 安装

安装commitlint插件

参考官网 install 命令commitlint.js.org/

shell 复制代码

// npm安装
npm install --save-dev @commitlint/cli @commitlint/config-conventional

// yarn安装
yarn add -D @commitlint/cli @commitlint/config-conventional

// pnpm 安装
pnpm add --save-dev @commitlint/{cli,config-conventional}
pnpm add -D @commitlint/cli @commitlint/config-conventional

创建commitlint.config.js文件

根目录创建commitlint.config.js文件，写入下面这段内容

shell 复制代码

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    // 自定义规则示例
    'type-enum': [2, 'always', [
      'feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore', 'revert'
    ]],
    'subject-case': [0] // 允许任意大小写
  }
};

安装husky

shell 复制代码

// npm
npm install --save-dev husky
// yarn
yarn add -D husky
// pnpm
pnpm add -D husky

初始化 Husky

npm or yarn

shell 复制代码

npx husky install
# 可选：在 package.json 中添加 prepare 脚本自动初始化
npm pkg set scripts.prepare="husky install"

pnpm

shell 复制代码

# 通过命令初始化 Husky 并自动在 package.json 中添加 prepare 脚本：
pnpm exec husky init
# .husky/pre-commit  删除掉，不然后面会报错
rm -f .husky/pre-commit

配置 commit-msg 钩子

npm or yarn

shell 复制代码

npx husky add .husky/commit-msg 'npx --no -- commitlint --edit ${1}'

pnpm

shell 复制代码

pnpm dlx husky add .husky/commit-msg 'pnpm commitlint --edit ${1}'
// 返回 husky add 已弃用 无法使用上面命令

直接写入

shell 复制代码

# 创建钩子文件并写入命令
echo "npx --no -- commitlint --edit $1" > .husky/commit-msg
# 赋予执行权限
chmod +x .husky/commit-msg

验证提交拦截

尝试提交一个不符合约定式提交的信息：

shell 复制代码

git commit -m "bad message"

你会看到类似以下报错，提交被阻止：

shell 复制代码

⧗   input: bad message
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

✖   found 2 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

修改为符合规范的提交，例如：

shell 复制代码

git commit -m "feat: add error handling"
# 预期：提交成功

Commitizen 适配器

如图所示

安装依赖

shell 复制代码

pnpm add -D commitizen @commitlint/cz-commitlint inquirer

配置 Commitizen 适配器

在项目根目录的 package.json 中，添加：

js 复制代码

{
  "scripts": {
    "commit": "git-cz"
  },
  "config": {
    "commitizen": {
      "path": "@commitlint/cz-commitlint"
    }
  }
}

使用方式

shell 复制代码

git add .
pnpm run commit

or

shell 复制代码

git add .
pnpm cz

中文配置

如图所示

安装中文提示适配器

shell 复制代码

pnpm add -D cz-conventional-changelog-zh-cn

修改 `package.json` 配置

js 复制代码

{
  "scripts": {
    "commit": "git-cz"
  },
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog-zh-cn"
    }
  }
}

自定义提交类型

cz-customizable

安装依赖

shell 复制代码

pnpm add -D cz-customizable

修改 `package.json` 配置

js 复制代码

"config": {
  "commitizen": {
    "path": "cz-customizable"
  }
}

遇到问题

1.package.json 配置了type：'moudle'

cz-customizable默认官方配置是使用的cjs

解决方法：

默认配置文件名为 .cz-config.js

将文件后缀改为cjs 无法识别

将配置文件命名为 .cz-config.js.json, 内容示例：

js 复制代码

{
  "types": [
    { "value": "feat", "name": "feat:     新功能" },
    { "value": "fix", "name": "fix:      修复bug" },
    { "value": "style", "name": "style:    代码样式（不影响功能）" },
    { "value": "refactor", "name": "refactor: 代码重构（既不是新增功能也不是修复bug）" },
    { "value": "chore", "name": "chore:    构建过程或辅助工具的变动" },
    { "value": "test", "name": "test:     测试" },
    { "value": "perf", "name": "perf:     性能优化" },
    { "value": "wip", "name": "wip:      开发中（Work in Progress）" },
    { "value": "ci", "name": "ci:       CI配置相关" }
  ],
  "scopes": [{ "name": "ui" }, { "name": "api" }],
  "messages": {
    "type": "选择一种你的提交类型:",
    "scope": "选择一个scope（可选）:",
    "customScope": "请输入自定义的scope:",
    "subject": "简短描述:\n",
    "body": "详细描述，使用 "|" 换行（可选）:\n",
    "footer": "关联关闭的issue，例如：#31, #34(可选):\n",
    "confirmCommit": "确定提交此内容吗？"
  },
  "allowCustomScopes": true
  "footerPrefix": ""
}

2.cz-customizable 无法输入自定义scope

此问题源自 cz-customizable 本身的一个已知 bug

解决方法：

安装cz-custom

shell 复制代码

pnpm add -D cz-custom

修改package.json配置

js 复制代码

"config": {
  "commitizen": {
    "path": "cz-custom"
  }
},

.cz-config.js.json需要添加 "allowEmptyScopes": true，这样才可以不填scope

内容示例：

js 复制代码

{
  "types": [
    { "value": "feat", "name": "feat:     新功能" },
    { "value": "fix", "name": "fix:      修复bug" },
    { "value": "style", "name": "style:    代码样式（不影响功能）" },
    { "value": "refactor", "name": "refactor: 代码重构（既不是新增功能也不是修复bug）" },
    { "value": "chore", "name": "chore:    构建过程或辅助工具的变动" },
    { "value": "test", "name": "test:     测试" },
    { "value": "perf", "name": "perf:     性能优化" },
    { "value": "wip", "name": "wip:      开发中（Work in Progress）" },
    { "value": "ci", "name": "ci:       CI配置相关" }
  ],
  "scopes": [{ "name": "ui" }, { "name": "api" }],
  "messages": {
  "type": "选择一种你的提交类型:",
    "scope": "选择一个scope（可选）:",
    "customScope": "请输入自定义的scope:",
    "subject": "简短描述:\n",
    "body": "详细描述，使用 "|" 换行（可选）:\n",
    "footer": "关联关闭的issue，例如：#31, #34(可选):\n",
    "confirmCommit": "确定提交此内容吗？"
  },
  "allowCustomScopes": true,
  "allowEmptyScopes": true,
  "footerPrefix": ""
}

commitlint安装和配置使用教程