Git提交规范神器！commitlint.config.js 完整配置指南

15次阅读

在团队协作开发中，Git提交信息（commit message）的规范性直接影响代码回溯效率、项目维护成本，甚至团队协作流畅度。很多项目中会出现“fix bug”“更新代码”这类模糊的提交信息，后续排查问题、追溯功能迭代时，往往要花费大量时间翻看代码变更，得不偿失。

而commitlint就是解决这一问题的利器——它能强制校验Git提交信息的格式，让每一条提交都清晰、规范，适配团队协作和项目长期维护。今天就来详细讲解如何配置commitlint.config.js，附上生产环境常用规则，新手也能直接复制使用。

一、先搞懂：commitlint 核心规则格式

在配置之前，首先要明确commitlint的规则定义格式，所有自定义规则都遵循这一规范，核心格式如下：

规则名: [校验等级, 生效模式, 限制值]

三个参数的具体含义，用通俗的语言解释清楚，避免专业术语晦涩难懂：

校验等级：0（禁用，不校验）、1（警告，提示但不阻断提交）、2（错误，直接阻断提交，生产环境首选）；
生效模式：always（始终生效）、never（永不生效）；
限制值：具体的规则约束，比如允许的提交类型、字符长度等。

提示：生产环境中，建议核心规则（如提交类型、提交描述）都设为校验等级2，避免不规范提交混入代码仓库。

二、直接可用：commitlint.config.js 完整配置（生产环境版）

以下是行业通用的完整配置（基于Angular规范，适配前端、后端、全栈等绝大多数项目），内置详细注释，复制到项目根目录的commitlint.config.js文件中，即可直接使用，无需额外修改：

// commitlint.config.js
// 核心作用：校验Git提交信息格式，规范团队提交规范
module.exports = {
  // 继承官方推荐的基础规则（无需自己从零编写基础规则）
  extends: ['@commitlint/config-conventional'],

  // 自定义校验规则（核心配置，可根据团队需求调整）
  rules: {
    // 1. 提交类型（type）规则：必填，且只能使用指定类型
    'type-enum': [
      2, // 错误等级：不满足规则直接阻断提交
      'always', // 始终生效
      [
        'feat',     // 新功能（如：新增用户登录功能）
        'fix',      // 修复bug（如：修复登录按钮点击无响应问题）
        'docs',     // 文档修改（如：更新README.md）
        'style',    // 代码格式调整（不影响代码运行，如：缩进、空格）
        'refactor', // 代码重构（既不是新增功能，也不是修复bug，如：优化代码结构）
        'test',     // 测试用例修改（如：新增单元测试、修改测试代码）
        'chore',    // 杂项修改（如：依赖更新、构建工具配置、.gitignore修改）
        'perf',     // 性能优化（如：减少接口请求时间、优化循环效率）
        'revert',   // 回滚提交（如：回滚到上一版本，撤销错误提交）
        'ci',       // CI/CD配置修改（如：Jenkins、GitHub Actions配置）
        'build'     // 构建系统修改（如：webpack、vite配置调整）
      ]
    ],
    // type必须为小写，避免出现Feat、FIX等不规范写法
    'type-case': [2, 'always', 'lower-case'],
    // type不能为空，禁止提交无类型的信息（如：直接提交"修改代码"）
    'type-empty': [2, 'never'],

    // 2. 作用域（scope）规则：可选，用于细分提交的模块（如：user、order、goods）
    'scope-case': [2, 'always', 'lower-case'], // scope必须小写
    'scope-empty': [0, 'always'], // 允许scope为空（不需要细分模块可保持默认，需要强制填写可改为[2, 'never']）

    // 3. 提交描述（subject）规则：提交信息的核心描述，简洁明了
    'subject-empty': [2, 'never'], // subject不能为空，禁止提交无描述的信息
    'subject-full-stop': [2, 'never', '.'], // subject末尾不能加句号，保持简洁
    // subject禁止使用指定大小写格式（避免首字母大写、全大写等不统一写法）
    'subject-case': [2, 'never', ['sentence-case', 'start-case', 'pascal-case', 'upper-case']],
    'header-max-length': [2, 'always', 50], // 提交信息头部（type(scope): subject）最大长度50字符，避免过长

    // 4. 提交正文（body）规则：详细描述提交的具体内容（可选，复杂修改建议填写）
    'body-leading-blank': [1, 'always'], // 正文前必须空一行，与subject区分开
    'body-max-line-length': [2, 'always', 100], // 正文每行最大长度100字符，避免换行混乱

    // 5. 提交页脚（footer）规则：用于标注关联的issue、bug编号等（可选）
    'footer-leading-blank': [1, 'always'], // 页脚前必须空一行，与body区分开
    'footer-max-line-length': [2, 'always', 100] // 页脚每行最大长度100字符
  }
};

三、灵活调整：常用自定义规则场景

上面的默认配置适配大多数项目，但不同团队的规范可能有差异，以下是3个最常用的自定义场景，直接修改对应规则即可：

场景1：强制填写作用域（scope）

如果项目模块清晰（如：用户模块、订单模块、商品模块），可以强制要求提交时填写scope，便于区分模块变更：

'scope-empty': [2, 'never'] // 改为2（错误等级），禁止scope为空

场景2：放宽提交信息长度限制

如果部分提交描述较长，可放宽header（头部）长度限制（默认50字符，可改为72字符）：

'header-max-length': [2, 'always', 72] // 头部最长72字符

场景3：新增自定义提交类型

如果团队有特殊需求（如：UI修改），可在type-enum中新增自定义类型：

'type-enum': [
  2,
  'always',
  [
    'feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore',
    'ui' // 新增：UI样式修改（如：调整按钮样式、页面布局）
  ]
]

四、关键步骤：让配置生效（必看）

配置好commitlint.config.js后，还需要安装依赖并验证，否则配置不会生效，步骤如下：

1. 安装依赖（项目根目录执行）

需要安装两个核心依赖：@commitlint/cli（commitlint核心工具）、@commitlint/config-conventional（官方基础规则）：

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

2. 验证配置是否生效

执行以下命令，测试一条符合规范的提交信息，验证配置是否正常工作：

echo "feat(user): add login button" | npx commitlint

✅ 验证结果说明：

无任何输出：校验通过，提交信息符合规范；
出现报错信息：根据报错提示修改提交信息（如：type错误、subject过长等）。

3. 进阶：配合husky实现提交时自动校验

上面的验证需要手动执行命令，实际开发中，可配合husky（Git钩子工具），实现“git commit”时自动校验，避免忘记校验：

# 安装husky（已安装可跳过）
npm install -D husky

# 启用husky
npx husky install

# 添加commit-msg钩子，执行commitlint校验
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1'

配置完成后，每次执行git commit -m “xxx”时，会自动校验提交信息，不符合规范会直接阻断提交。

五、常见问题排查

问题1：执行校验命令报错“command not found: commitlint”？解决：检查依赖是否安装成功，可重新执行npm install，或使用npx commitlint（避免全局安装）。
问题2：提交信息符合规则，但仍报错？解决：检查提交信息是否有多余空格（如：type后多打了空格），或规则配置是否有语法错误（如：数组逗号遗漏）。
问题3：husky钩子不生效？解决：确认husky已启用（npx husky install），且commit-msg钩子文件已创建，可重新执行npx husky add命令。
问题4：执行vite相关命令报错“vite: command not found”？解决：核心原因是vite未安装或未配置环境变量，分3种场景处理：1. 未安装vite：执行npm install -D vite（局部安装，适配项目）或npm install -g vite（全局安装，可全局调用）；2. 已局部安装但报错：需通过npx vite（临时调用）或在package.json中配置scripts脚本（如”dev”: “vite”），再执行npm run dev；3. 全局安装仍报错：检查系统环境变量是否配置了Node.js的全局bin目录（Windows：查看Path是否包含%USERPROFILE%\AppData\Roaming\npm，Mac/Linux：查看~/.bashrc或~/.zshrc是否包含/usr/local/bin），配置后重启终端即可。