搭建现代化 Git 提交规范：commitlint + czg + husky + lint‑staged 完整实战

在团队协作开发中，杂乱无章的 Git 提交记录（如 修改代码、修复bug、更新文件）会严重影响项目维护、版本迭代、日志追溯。为了统一团队提交风格、规范化代码提交行为、实现自动代码校验与格式化、支持自动生成版本更新日志，本文将从零落地一套企业级现代化 Git 提交规范方案。

整套方案基于 husky + commitlint + czg + lint-staged 实现，支持中文交互式提交 、强制校验提交信息格式 、提交前自动修复代码格式，适配 Windows/Mac 全环境，完美适配新旧项目。

一、技术栈核心作用详解

本次落地用到的四个核心依赖，各司其职、相互配合，构成完整的 Git 提交校验闭环：

依赖工具	核心作用
husky	接管 Git 原生钩子（hook），在 `git commit` 前后触发自定义脚本，是所有校验的底层载体
@commitlint/cli	提交信息校验核心，强制校验 commit 文案格式，不符合规范直接阻断提交
@commitlint/config-conventional	官方规范预设，基于主流 Angular 提交规范，定义标准的提交类型与格式
czg	中文交互式提交工具，替代手动手写 commit，可视化选择提交类型，自动生成规范文案，规避人为写错格式问题
lint-staged	仅对 Git 暂存区（staged）文件执行 ESLint/Prettier 格式化校验，速度极快，避免全量扫描项目文件

核心逻辑区分

czg：辅助生成规范的提交信息（解决「不会写、写错格式」问题）
commitlint：强制校验提交信息（解决「乱写提交文案」问题）
lint-staged：强制校验代码格式（解决「脏代码、不规范代码入库」问题）
husky：串联所有校验流程，实现自动化拦截

二、Conventional Commits 标准规范

整套校验体系基于通用的约定式提交规范，标准格式如下：

xml 复制代码

<type>(<scope>): <subject>

<body>

<footer>

字段说明

type（必填） ：提交类型，固定枚举值，代表本次变更性质
scope（可选） ：影响模块/功能范围，如 user、order、login，无范围可省略
subject（必填） ：简短变更描述，简洁清晰，不超过100字符
body（可选） ：详细变更说明、修改原因
footer（可选） ：关联 issue、破坏性变更说明

通用 Type 类型对照表

提交类型 Type	功能说明
`feat`	新增功能
`fix`	修复线上/测试 Bug
`docs`	文档、注释更新
`style`	代码格式调整（不影响业务逻辑）
`refactor`	代码重构（无新增功能、无 Bug 修复）
`perf`	性能优化
`test`	新增/修改测试用例
`build`	构建脚本、依赖、打包配置变更
`ci`	CI/CD 流水线配置修改
`chore`	工程配置、工具、杂项修改（无业务代码变更）
`revert`	回滚历史提交

三、完整环境搭建步骤

适配 Node.js 项目（Vue/React/原生JS/TS 通用），支持 Husky 9+ 最新版本，修复官方废弃命令警告。Node 版本 > 20

1. 安装全套依赖

bash 复制代码

npm install husky @commitlint/cli @commitlint/config-conventional czg lint-staged eslint prettier typescript-eslint -D

2. 初始化 Husky

Husky 9+ 废弃了 husky install 旧命令，统一使用 husky init 初始化：

csharp 复制代码

npx husky init

执行后自动生成 .husky 钩子目录，并自动在 package.json 写入自动激活脚本。

3. 配置团队自动激活钩子

修改 package.json，确保团队成员拉取代码、安装依赖后，自动启用 Husky，无需手动操作：

json 复制代码

{
  "scripts": {
    "prepare": "husky"
  }
}

4. 创建提交信息校验钩子（commit-msg）

作用：提交完成前，校验 commit 文案格式，非法直接拦截。在 .husky/commit-msg 写入以下内容（Husky9+ 无需旧的 shell 头部代码）：

css 复制代码

npx --no-install commitlint --edit $1

5. 创建代码格式化校验钩子（pre-commit）

作用：提交前自动执行 lint-staged，修复暂存区代码格式问题。在 .husky/pre-commit 写入：

bash 复制代码

node node_modules/lint-staged/bin/lint-staged.js

四、全套核心配置文件

1. commitlint.config.js（根目录）

整合 提交格式校验规则 + czg 中文交互式配置，修复所有版本报错问题，可直接复制使用：

css 复制代码

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    // type 必须小写
    'type-case': [2, 'always', 'lowerCase'],
    // 禁止空 type
    'type-empty': [2, 'never'],
    // 禁止空描述
    'subject-empty': [2, 'never'],
    // 禁止描述末尾带句号
    'subject-full-stop': [0, 'never'],
    // scope 可选、允许为空
    'scope-empty': [0, 'always']
  },
  // czg 中文交互弹窗配置
  prompt: {
    messages: {
      type: '请选择提交类型：',
      scope: '请填写影响范围(可选，例如：core、ui、plugin)：',
      customScope: '自定义范围：',
      subject: '简短描述本次变更(必填，不超过100字符)：',
      body: '详细描述(可选，换行使用 | 符号换行)：',
      breaking: '是否存在破坏性变更？(y/N)',
      breakingSubject: '破坏性变更说明：',
      footerPrefixsSelect: '选择关联issue类型：',
      customFooterPrefixs: '自定义issue前缀：',
      footer: '填写关联issue编号，例如 #123：',
      confirmCommit: '确认提交以上内容？'
    },
    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:       🎡 CI流水线配置改动' },
      { value: 'chore', name: 'chore:    🧹 工程配置、工具杂项修改' },
      { value: 'revert', name: 'revert:   ⏪ 回滚某次提交' }
    ],
    useEmoji: true,
    emojiAlign: 'left',
    allowCustomIssuePrefixs: true,
    allowEmptyIssuePrefixs: true,
    maxSubjectLength: 100,
    minSubjectLength: 0,
    scopeOverrides: null,
    defaultScope: '',
    // 跳过issue关联提问，如需关联issue删除该行
    skipQuestions: ['footerPrefixsSelect','footer']
  }
}

2. package.json 完整配置

包含交互式提交脚本、自动激活 Husky、lint-staged 代码校验规则，与上述配置完全适配：

perl 复制代码

{
  "name": "your-project",
  "version": "1.0.0",
  "engines": {
    "node": ">20",
    "npm": ">10"
  },
  "scripts": {
    "prepare": "husky",
    "commit": "npx czg"
  },
  "devDependencies": {
    "@commitlint/cli": "^19.5.0",
    "@commitlint/config-conventional": "^19.5.0",
    "czg": "^1.14.0",
    "husky": "^9.1.6",
    "lint-staged": "^15.2.10",
    "eslint": "^9.0.0",
    "prettier": "^3.0.0",
    "typescript-eslint": "^8.68.0",
  },
  "lint-staged": {
    "*.{ts,js}": ["eslint --fix", "prettier --write"],
    "*.{json,md,vue,html}": ["prettier --write"]
  }
}

3 eslint.config.mjs 完整配置

css 复制代码

import typescriptEslint from "typescript-eslint";

export default [{  files: ["**/*.ts"],
}, {
  plugins: {
    "@typescript-eslint": typescriptEslint.plugin,
  },

  languageOptions: {
    parser: typescriptEslint.parser,
    ecmaVersion: 2022,
    sourceType: "module",
  },

  rules: {
    "@typescript-eslint/naming-convention": ["warn", {
      selector: "import",
      format: ["camelCase", "PascalCase"],
    }],

    curly: "warn",
    eqeqeq: "warn",
    "no-throw-literal": "warn",
    semi: "warn",
  },
}]; v

五、项目使用教程

1. 标准提交流程（推荐）

csharp 复制代码

# 1. 将修改文件加入暂存区
git add .

# 2. 启动中文交互式提交
npm run commit

按照终端中文提示依次选择：提交类型 → 填写模块范围（可选）→ 填写变更描述 → 确认提交，自动生成规范 commit 信息并完成提交。

2. 非法提交拦截测试

手动书写不规范的提交信息，会被自动拦截报错：

sql 复制代码

git commit -m "修复bug"

效果：commitlint 检测到格式非法，直接阻断提交，强制规范团队提交行为。

3. 紧急跳过校验（仅临时使用，不推荐）

sql 复制代码

git commit -m "chore: 紧急临时修改" --no-verify

六、完整工作流程原理图

七、工程化扩展能力

自动生成版本日志 ：搭配 standard-version，根据规范 commit 自动生成 CHANGELOG.md、自动升级版本号
CI 二次校验：在 GitHub/GitLab 流水线配置 commitlint 校验，防止本地绕过校验直接推送代码
自定义提交类型：根据业务场景新增专属 type，适配团队业务规范
编辑器联动：搭配 VSCode Commitlint 插件，实时提示提交格式错误

八、最终落地文件清单

项目提交 Git 的核心规范文件，缺一不可：

commitlint.config.js：校验规则 + 中文交互配置
.husky/commit-msg：提交信息校验钩子
.husky/pre-commit：代码格式校验钩子
package.json：脚本、依赖、lint-staged 配置

九、落地总结

这套方案彻底解决了团队 Git 提交不规范、代码格式混乱、日志难以追溯的问题，兼具易用性与强制性：

新手友好：中文可视化提交，无需记忆复杂规范
强制约束：双重钩子拦截，杜绝不规范提交
高效智能：仅校验变更文件，自动修复代码格式
工程通用：适配所有前端/Node.js 项目，开箱即用