在前两篇文章中，我们先后拆解了 Conventional Commits 约定式提交规范，又配置了 Commitlint + Husky + lint-staged 工程化工具链，实现了“不规范Commit信息拦截”。但实际使用中，还是会遇到一个痛点：

即便知道规范格式（如 feat(模块): 新增XX功能），新手仍会记混 type 枚举、写错格式，甚至遗漏 scope；老开发者也可能因疏忽，写出不符合要求的Commit信息，导致提交被拦截，反复修改浪费时间。

而 Commitizen 的出现，完美解决了这个问题——它提供交互式命令行引导，不用记任何规范格式，跟着提示一步步选择、输入，就能自动生成符合 Conventional Commits 规范的Commit信息，配合我们之前配置的Commitlint，彻底实现“零记忆、零错误、高效率”的提交。

本文将手把手教你配置 Commitizen，从依赖安装、配置步骤，到实战使用、异常排查，全程实操无冗余，新手也能快速上手，让你的 Git 提交更规范、更高效，无缝衔接前文的工程化配置。

一、先搞懂：Commitizen 到底能解决什么问题？

在配置前，先明确 Commitizen 的核心价值，以及它和我们前文配置的工具（Commitlint、Husky）的关系，避免混淆：

1. 核心痛点（为什么需要 Commitizen？）

• 记不住规范：新手记不住 type 枚举（feat/fix/docs 等）、格式要求（scope 可选、description 首字母小写等），频繁写错；
• 提交效率低：每次提交都要手动组织Commit信息格式，生怕写错被拦截，反复修改耗时；
• 团队不统一：即便有Commitlint拦截，部分开发者仍会敷衍修改，导致Commit信息虽符合规范，但语义模糊、不够详细。

2. Commitizen 核心作用

Commitizen 是一个“交互式Commit信息生成工具”，核心功能的是：替代 git commit -m "xxx" 命令，通过命令行交互，引导你选择 type、输入 scope、填写 description、body、footer，最终自动生成符合 Conventional Commits 规范的Commit信息。

简单说：不用记格式，跟着提示点一点、输一输，就能生成规范的Commit信息，再也不会被Commitlint拦截。

3. 与前文工具的协同逻辑（关键）

很多人会疑惑：已经有了Commitlint校验，为什么还要用Commitizen？两者不是重复的，而是互补协同：

Commitizen → 负责“生成规范的Commit信息”（从源头避免错误）；

Commitlint + Husky → 负责“校验Commit信息”（兜底拦截，防止特殊情况遗漏）。

协同流程：执行 npm run commit（Commitizen交互式引导）→ 生成规范Commit信息 → Husky触发commit-msg钩子 → Commitlint校验（此时基本不会失败）→ 完成提交。

二、环境准备：前置条件（必看）

Commitizen 需依赖前文配置的基础环境，确保你的项目已满足以下条件，避免配置失败（如果已经配置过Commitlint + Husky，可直接跳过）：

• 项目已初始化 Git（执行过 git init）；
• 项目已初始化 npm/yarn/pnpm（有 package.json 文件）；
• 项目已配置 Commitlint + Husky（核心依赖：@commitlint/cli、@commitlint/config-conventional、husky）；
• 推荐依赖版本（避坑关键）：Commitizen 4.x 版本（稳定兼容前文的Commitlint 17.x、Husky 8.x）。

三、分步配置：从0到1配置Commitizen（全程实操）

以下配置步骤基于 npm（yarn/pnpm 可对应替换命令，如 yarn add 替换 npm install），步骤简单，全程复制命令即可，新手也能轻松跟上。

第一步：安装核心依赖

执行以下命令，安装 Commitizen 核心依赖，以及适配 Conventional Commits 规范的适配器（关键）：

# 安装Commitizen（核心工具）
npm install --save-dev commitizen

# 安装适配器：适配Conventional Commits规范（和Commitlint规则一致）
npm install --save-dev cz-conventional-changelog

说明：

• cz-conventional-changelog：是 Commitizen 的官方适配器，内置了 Conventional Commits 规范的交互逻辑，和我们前文配置的 @commitlint/config-conventional 规则完全匹配，无需额外自定义；
• 如果不安装适配器，Commitizen 无法提供交互式引导（会报错），这是新手最容易踩的坑。

第二步：配置Commitizen（两种方式，选一种即可）

配置的核心是：告诉 Commitizen 使用哪个适配器（cz-conventional-changelog），有两种配置方式，推荐第一种（简洁，无需新增文件）。

方式1：在 package.json 中配置（推荐）

直接在项目根目录的 package.json 中，新增 config 配置和 scripts 脚本，方便后续执行交互式提交：

{
  "name": "your-project",
  "version": "1.0.0",
  // 其他配置（如dependencies、lint-staged等，保留不变）
  "scripts": {
    // 新增：交互式提交脚本，后续执行 npm run commit 即可
    "commit": "cz",
    // 其他脚本（如prepare、lint等）
  },
  // 新增：配置Commitizen适配器
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog"
    }
  }
}

配置说明：

• "path": "./node_modules/cz-conventional-changelog"：指定 Commitizen 使用的适配器路径，确保能找到我们安装的适配器；
• "commit": "cz"：简化命令，后续不用记复杂的 npx cz，直接执行 npm run commit 就能启动交互式引导。

方式2：创建单独配置文件（适合配置复杂的场景）

如果不想在 package.json 中添加过多配置，可在项目根目录创建 .czrc 文件，写入以下内容：

{
  "path": "cz-conventional-changelog"
}

说明：这种方式和方式1效果完全一致，只是配置文件单独存放，后续同样执行npm run commit（需在package.json中新增commit脚本）启动交互。

第三步：验证配置（简单两步，确认生效）

配置完成后，不用复杂操作，简单两步就能验证是否生效：

1. 随便修改项目中的一个文件（如 index.js），添加到暂存区： git add .
2. 执行交互式提交命令： npm run commit预期结果：终端出现交互式提示（如下），说明配置成功，接下来就能跟着提示填写Commit信息了。

? Select the type of change that you're committing: (Use arrow keys)
❯ feat:     A new feature
  fix:      A bug fix
  docs:     Documentation only changes
  style:    Changes that do not affect the meaning of the code
  refactor: A code change that neither fixes a bug nor adds a feature
  test:     Adding missing tests or correcting existing tests
  chore:    Changes to the build process or auxiliary tools

四、实战使用：手把手教你用Commitizen提交代码

配置生效后，后续提交代码，不再使用 git commit -m "xxx"，而是执行 npm run commit，跟着交互式提示一步步操作，全程不用记格式，每一步都有明确引导，新手也能轻松上手。

完整交互流程（以“修复登录模块验证码过期bug”为例），每一步都有详细说明：

步骤1：选择Commit类型（type）

? Select the type of change that you're committing: (Use arrow keys)
❯ feat:     A new feature
  fix:      A bug fix
  docs:     Documentation only changes
  style:    Changes that do not affect the meaning of the code
  refactor: A code change that neither fixes a bug nor adds a feature
  test:     Adding missing tests or correcting existing tests
  chore:    Changes to the build process or auxiliary tools

操作：按上下箭头选择对应的type，这里我们修复bug，选择 fix，按回车确认。

提示：type的含义和我们前文Commitlint配置的完全一致，新增功能选feat、修复bug选fix，无需额外记忆。

步骤2：输入影响范围（scope，可选）

? What is the scope of this change (e.g. component or file name): (press enter to skip)
登录

操作：输入本次提交影响的模块/范围（如登录、首页、用户中心），也可以直接按回车跳过（scope是可选的）。这里我们输入 登录，按回车确认。

提示：scope建议填写，能让Commit信息更清晰，后续追溯代码更高效（如 fix(登录): 修复验证码过期bug）。

步骤3：输入简短描述（subject，必填）

? Write a short, imperative tense description of the change (max 50 chars):
修复手机号验证码过期的bug

操作：输入本次提交的核心描述，要求简短（不超过50字符）、 imperative 语气（祈使句，如“修复xxx”“新增xxx”），首字母小写（Commitizen会自动处理，无需刻意修改）。

提示：这部分对应Commit信息的 description 部分，是必填项，也是Commitlint重点校验的内容，Commitizen会自动限制长度，避免违规。

步骤4：输入详细描述（body，可选）

? Provide a longer description of the change: (press enter to skip)
1. 修复手机号验证码5分钟过期后，仍能提交的问题；
2. 优化验证码过期提示文案，更清晰易懂。

操作：输入本次提交的详细说明（如修改原因、修改内容、影响范围等），可换行，直接按回车跳过（简单提交可省略）。

提示：body部分用于补充说明，适合复杂提交，让团队成员快速了解本次修改的细节。

步骤5：输入重大变更说明（footer，可选）

? Are there any breaking changes? (y/N)
N

操作：询问是否有重大变更（breaking changes，如API修改、功能删除等），有则输入y，无则输入N（默认），按回车确认。

若选择y，会进一步提示输入重大变更的描述，用于告知团队成员本次修改可能带来的影响，需谨慎填写。

步骤6：确认提交，自动生成规范Commit信息

所有步骤完成后，终端会显示生成的Commit信息，确认无误后，按回车即可完成提交：

? Confirm commit? (fix(登录): 修复手机号验证码过期的bug
1. 修复手机号验证码5分钟过期后，仍能提交的问题；
2. 优化验证码过期提示文案，更清晰易懂。) (Y/n)
Y

提交成功后，终端会显示提交记录，生成的Commit信息如下（完全符合Conventional Commits规范，不会被Commitlint拦截）：

fix(登录): 修复手机号验证码过期的bug

1. 修复手机号验证码5分钟过期后，仍能提交的问题；
2. 优化验证码过期提示文案，更清晰易懂。

五、常见异常排查：配置/使用失败？看这里

配置和使用过程中，新手可能会遇到一些小异常，以下是最常见的4种问题及解决方案，帮你快速避坑，衔接前文的异常排查逻辑：

异常1：执行 npm run commit 报错，提示“cz: command not found”

原因：Commitizen 未正确安装，或依赖安装不完整。

解决方案： # 1. 重新安装Commitizen和适配器 ``npm uninstall --save-dev commitizen cz-conventional-changelog ``npm install --save-dev commitizen cz-conventional-changelog `` ``# 2. 检查package.json中是否有commit脚本和config配置，确保无误 ``# 3. 若仍报错，直接执行npx cz启动交互（跳过npm脚本） ``npx cz

异常2：启动交互后，没有type选项，提示“No adapter found”

原因：未安装适配器（cz-conventional-changelog），或适配器路径配置错误。

解决方案： 确认已安装适配器：npm install --save-dev cz-conventional-changelog；检查配置路径：package.json中 "path" 需填写 ./node_modules/cz-conventional-changelog（不要遗漏路径）。

异常3：交互式生成的Commit信息，仍被Commitlint拦截

原因：Commitizen 适配器的规则，与 Commitlint 的自定义规则不匹配（如Commitlint新增了自定义type，而适配器中没有）。

解决方案： 若Commitlint新增了自定义type（如perf、pay），需修改适配器配置（下文进阶优化会讲）；检查Commitlint配置中的 rules 规则（如subject-max-length），确保交互式输入的内容符合规则（如description不超过50字符）。

异常4：执行 npm run commit 后，提示“working tree clean”

原因：没有未提交的文件，暂存区为空（git add 未执行）。

解决方案：先修改项目文件，执行 git add . 将文件添加到暂存区，再执行 npm run commit。

六、进阶优化：让Commitizen更贴合团队需求

基础配置完成后，可根据团队的实际规范，对Commitizen进行进阶优化，让交互式提交更贴合项目场景，衔接前文的进阶优化逻辑：

1. 新增自定义type（适配Commitlint自定义规则）

如果前文的Commitlint配置中，新增了自定义type（如perf、pay），默认的适配器（cz-conventional-changelog）中没有这些选项，此时需要自定义适配器配置：

配置完成后，重启交互式提交，就能看到新增的自定义type和scope选项，完美适配Commitlint的自定义规则。

2. 简化交互步骤（适合简单提交）

1. 安装自定义适配器依赖： npm install --save-dev cz-customizable

如果团队提交以简单修改为主，不需要body和footer，可在 .cz-config.js 中添加配置，跳过不必要的步骤：

1. 在项目根目录创建 .cz-config.js 文件，配置自定义type：

// .cz-config.js  
module.exports = {  
// 自定义type选项（和Commitlint的type-enum保持一致）  
 types: [  
	 { value: 'feat', name: 'feat: 新增功能' },  
	 { value: 'fix', name: 'fix: 修复bug' },  
	 { value: 'docs', name: 'docs: 文档更新' },  
	 { value: 'style', name: 'style: 代码风格调整' },  
	 { value: 'refactor', name: 'refactor: 代码重构' },  
	 { value: 'test', name: 'test: 测试相关' },  
	 { value: 'chore', name: 'chore: 构建/依赖/工具相关' },  
	 { value: 'perf', name: 'perf: 性能优化' }, // 自定义type  
	 { value: 'pay', name: 'pay: 支付相关功能' } // 自定义type  
 ],  
// 可选：自定义scope选项，让用户选择，不用手动输入  
scopes: [  
	 { name: '登录' },  
	 { name: '首页' },  
	 { name: '用户中心' },  
	 { name: '支付' }  
],  
// 其他配置（保持默认即可）  
messages: {  
	type: '请选择Commit类型：',  
	scope: '请选择影响范围（可选）：',  
	subject: '请输入简短描述（必填，不超过50字符）：',  
	body: '请输入详细描述（可选）：',  
	breaking: '是否有重大变更？(y/N)：',  
	confirmCommit: '确认提交？(Y/n)：'  
},  
// 限制subject长度  
subjectLimit: 50  
};

3. 修改 package.json 中的配置，指定自定义适配器： "config": { `` "commitizen": { `` "path": "cz-customizable" `` } ``}

module.exports = {
  // 其他配置不变
  skipQuestions: ['body', 'breaking'], // 跳过body和重大变更询问
  subjectLimit: 50
};

3. 全局安装Commitizen（所有项目通用）

如果需要在多个项目中使用Commitizen，无需每个项目都安装，可全局安装：

# 全局安装Commitizen和适配器
npm install -g commitizen cz-conventional-changelog

# 全局配置适配器
commitizen init cz-conventional-changelog --save-dev --save-exact

配置完成后，所有项目中只需执行 git cz，就能启动交互式提交，无需单独配置。

七、总结

Commitizen 看似是一个“辅助工具”，但它完美解决了“规范落地难、新手记不住格式”的核心痛点，与我们前文配置的 Commitlint + Husky 工具链结合，形成了“生成规范 → 校验规范 → 拦截错误”的完整闭环，让 Git 提交规范真正落地到每一次提交中。

本文的配置步骤简单易懂，全程实操，无论是新手还是老开发者，都能快速上手；基础配置可直接照搬，进阶配置可根据团队需求调整，适配不同项目场景。

使用 Commitizen 后，你会发现：提交代码不再需要记格式、不再担心被拦截，交互式引导既高效又规范，团队的Commit信息会变得统一、清晰，后续的代码追溯、代码审查也会变得更高效。

结合我们之前的系列文章，目前已经完成了「规范定义 → 工程化校验 → 交互式生成」的完整流程，下一篇我们将讲解如何用 standard-version 自动生成 CHANGELOG 和管理版本号，让 Git 工程化流程更完整。

最后，附上Commitizen常用命令速查表，方便日常查阅：

# 核心命令
npm install --save-dev commitizen cz-conventional-changelog # 安装依赖
npm run commit # 启动交互式提交（推荐）
npx cz # 直接启动交互式提交（跳过npm脚本）

# 进阶命令
npm install --save-dev cz-customizable # 安装自定义适配器
npm install -g commitizen cz-conventional-changelog # 全局安装

# 常见异常排查
1. 命令报错：重新安装依赖，检查配置路径
2. 无type选项：安装cz-conventional-changelog适配器
3. 被Commitlint拦截：确保适配器type与Commitlint配置一致

希望本文能帮你快速上手Commitizen，让你的Git提交更规范、更高效，无缝衔接前文的工程化配置！