见过太多这样的场景：代码写得漂漂亮亮，到了git commit这一步，随手甩一句fix bug或update就交差了。等三个月后真要回查某次改动，git log里全是fix xxx、update、temp这种信息，想定位一个具体功能变更，简直像在垃圾堆里翻钥匙。Commitizen 就是为解决这个问题而生的。它通过交互式问答引导你写结构化的提交信息，把feat(api): add user login endpoint这种一眼能看懂的提交，从口号变成默认动作。只要团队里有人开始用，其他人看到生成的提交信息，自然也会跟着规范化。这篇文章就围绕 Commitizen 的交互式提交流程，讲清楚它背后的设计逻辑、完整配置方法、实操细节，以及我在真实项目里踩过的坑和落地经验。
1. 为什么需要 Commitizen：提交信息混乱的根源
1.1 手动提交的真实痛点
如果你在一个超过三个人的团队里待过，大概率见过下面这些提交信息：
fix bug update modify something aaa这些信息不是不能用，但问题在于它造成了严重的信息损耗。git log、git blame、Code Review 时的提交上下文、甚至 release notes 的自动生成，全部依赖提交信息的质量。一条fix bug，你完全看不出它修了什么模块的什么问题，看不出是不是包含破坏性变更，也看不出它对应哪个需求单或 issue。当线上出问题需要排查改动来源时，你只能在git log里一条条点开 diff，效率极低。
我还见过一种更隐蔽的混乱：提交信息写得很长，但没有任何结构。比如把"修改了登录模块的token逻辑，顺便优化了首页布局，还更新了文档"全塞在一行里。这种信息在写的时候感觉省事，但在 review 和回溯的时候极其痛苦。提交信息本质上是异步沟通工具，它在你写完代码几个月后还要继续被人读。写得越随意，欠下的技术债越多。
1.2 约定式提交规范（Conventional Commits）是什么
为了解决这种混乱，Angular 团队在推行 AngularJS 开发流程时提出了一套提交信息规范，后来发展成社区广泛使用的 Conventional Commits 规范。它的核心格式非常简单：
<type>(<scope>): <subject> <BLANK LINE> <body> <BLANK LINE> <footer>其中type表示提交类型，比如feat表示新功能、fix表示修复；scope表示影响范围，比如模块名、组件名；subject是标题，要求用祈使句，尽量精简；body是详细描述；footer用来放破坏性变更说明和关联的 issue。
这个规范最有价值的地方是它把提交信息分成了"机器可读"和"人可读"两个层面。机器层面：通过feat、fix等类型，CI/CD 工具可以自动判定版本号应该升 minor 还是 patch，甚至自动生成 changelog。人可读层面：扫一眼feat(auth): add refresh token rotation，你就知道这次改动做了什么，影响哪个模块，和令牌刷新有关，信息密度极高。
1.3 Commitizen 的定位：把规范从"靠自觉"变成"走流程"
规范本身不复杂，难的是长期稳定执行。靠文档、靠 Code Review 时口头提醒，基本都会被大家当作没看见。Commitizen 的突破点在于：它把"写提交信息"这件事从"空白的命令行输入框"转变为"一步步交互式问答的表单"。
你不需要背规范、不需要记类型、不需要考虑格式。Commitizen 会像面试官一样问你一个个问题：这次变更的类型是什么？影响范围是哪个模块？标题写什么？有没有破坏性变更？关联哪个 issue？你只管回答，最终符合规范的提交信息由它生成。这也是 Commitizen 被设计成一个交互式 CLI 而不是一个校验工具的原因——它不是在你犯错后惩罚你，而是在你动手之前就通过流程帮你避开了犯错的可能。
2. 核心原理与工具链拆解
2.1 CLI + Adapter 架构：一次解耦，处处复用
要理解 Commitizen 的交互式提交流程，先得明白它的架构。Commitizen 本身是一个命令行工具（cz-cli），但实际上它只负责"交互主流程"，具体的提问内容、可选类型、字段规则，是由一个独立的"适配器"（adapter）来定义的。
这个设计非常像开发中常见的"策略模式"。cz-cli是骨架，Adapter 是血肉。GitHub 上常见的 adapter 有：
| Adapter | 特点 |
|---|---|
| cz-conventional-changelog | 官方默认，完全遵循 Conventional Commits 规范 |
| cz-customizable | 允许自定义提问文案、类型列表、字段规则 |
| cz-emoji | 在提交信息中加入 emoji 标识，适合个人项目 |
| cz-jira-smart-commit | 适配受 Jira Smart Commit 约束的团队 |
这种解耦带来的直接好处是：团队可以复用同一套交互流程，但用不同 adapter 来调整具体规则。比如你所在团队有成体系的内部规范，不想被 Conventional Commits 绑死，就可以用cz-customizable自定义字段提示，同时仍然保留交互式引导的体验。我在实际项目中就见过一个团队把 type 列表定制成业务名，比如module-projectA、module-projectB这种，因为他们的发布流程根本不需要区分feat和perf，只用关心模块归属。
2.2 适配器字段与提交格式的映射
以最常见的cz-conventional-changelog为例，它会在交互流程中依次问这些问题：
- Select the type of change that you're committing（选择提交类型）
- What is the scope of this change?（影响范围）
- Write a short, imperative tense description of the change（简短标题）
- Provide a longer description of the change（详细描述，可跳过）
- Are there any breaking changes?（是否存在破坏性变更）
- Does this change affect any open issues?（是否关联 issue）
这些问题看似简单，实际上每一个都精确对应了 Conventional Commits 格式中的某个部分。用一句话总结：适配器问什么，生成出来的git commit信息就包含什么。type对应第一个斜杠前的单词，scope对应斜杠后的括号，subject对应冒号后的标题，body和footer分别在空行后拼接。所以当你看到一个 Commitizen 生成的提交信息：
feat(api): add user login endpoint Add a new endpoint that allows users to login with email and password. Closes #42你应该能反向推断出用户刚才做了哪些交互选择：第一题选了feat，第二题填了api，第三题填了add user login endpoint，第四题填写了以Add a new endpoint开头的那段描述，第六题选择了是并填入了#42。
2.3 为什么要限制 subject 不超过 87 字符
有个经常被忽略但很值得解释的细节：cz-conventional-changelog在询问标题时会给一个长度限制，默认是 87 个字符。这不是随便定的数字。Git 底层在存储提交对象时，提交信息的头部如果过长，默认的git log格式化显示会被截断；更重要的是，很多工具（比如 GitHub、GitLab 的提交列表）在渲染时会固定显示第一行，太长的标题会被打省略号，导致信息不完整。
87 这个数字也不是 cz-conventional-changelog 拍脑袋定的。在大多数终端宽度为 80 字符的场景下，加上type(scope):的前缀以后，剩余可写空间大概就是 87 字符左右。这意味着"标题一行，终端一屏"，无论用什么工具看提交信息，都不会出现被迫横向滚动或被动截断的情况。所以在实操中我会特别注意：subject 要短，具体细节放到 body 部分，而不是硬塞进标题。
3. 环境准备与安装步骤
3.1 全局安装还是项目局部安装
Commitizen 推荐作为项目的开发依赖安装，而不是全局安装。原因很现实：如果开发者全局装了 Commitizen，换了电脑、换了 CI 机器就没了；而把它写进package.json的devDependencies，任何 clone 项目的人执行npm install后都会自动拥有完整的提交工具链。对一个团队项目来说，这种"开箱即用"的体验价值远大于全局安装的方便。
不过全局安装也不完全是禁区。如果你是个人维护多个项目、又懒得一个个配置，npm install -g commitizen后直接在任何仓库里执行git cz也很顺畅。我个人的习惯是两者都装：全局装一套用于快速体验，项目里再局部装一套用于正式团队协作。项目里装的版本可以通过package.json锁得比较精确，全局版本则保持较新，互不影响。
3.2 初始化适配器与 package.json 配置
推荐在一个 Node.js 项目根目录下执行：
npx commitizen init cz-conventional-changelog --save-dev --save-exact这条命令做了三件事：安装cz-conventional-changelog到项目的 devDependencies、在 package.json 中写入适配器路径配置、打印下一步使用提示。--save-exact参数表示锁定精确版本号，避免以后适配器升级导致交互流程突然变化，这一点在团队项目中尤其重要。
执行完毕后检查 package.json，你会看到多出来类似下面的内容：
{ "scripts": { "commit": "cz" }, "config": { "commitizen": { "path": "./node_modules/cz-conventional-changelog" } }, "devDependencies": { "commitizen": "^4.3.1", "cz-conventional-changelog": "^3.3.0" } }需要特别说明的一点：config.commitizen.path字段指定了默认使用的适配器位置。当项目里有多个适配器时，这个字段决定了git cz启动后走哪套交互逻辑。我遇到过不少项目配置出错的情况，根因基本都在这个 path 指向了不存在的包名，或者 monorepo 子包中依赖没有提升到根目录导致路径失效。
3.3 用 Husky 和 Commitlint 补上强制约束
Commitizen 只负责"帮你生成规范的提交信息"，它不保证团队成员一定会用它。有人就是喜欢我行我素地git commit -m "hack"，你再怎么引导也拦不住。这时候就需要另一层兜底：commit-msg 钩子 + commitlint。
我的推荐组合是 Husky 负责 Git Hooks 管理，commitlint 负责校验提交信息是否符合 Conventional Commits 规范。安装和配置大致是这样的：
npm install --save-dev husky @commitlint/cli @commitlint/config-conventional npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'然后在项目根目录创建commitlint.config.js：
module.exports = { extends: ['@commitlint/config-conventional'] };这样配置之后，任何人不管用什么方式提交，只要提交信息不符合规范，commit-msg 钩子就会直接报错，提交被中断。Commitizen 是"引导"，Husky + Commitlint 是"强制"，两者配合才算完整的规范闭环。我带的项目里就这么干：能走git cz的用交互式表单，非要写裸命令的，不规范的提交根本进不了 Git 历史。
4. 交互式提交深度实操：一步步拆解
4.1 启动交互式提交的三种方式
初始化好适配器之后，启动交互式提交有以下三种常见方式：
git cz npx cz npm run commitgit cz是全局安装 Commitizen 时提供的 Git 子命令，体验最顺滑；npx cz适合不想全局安装、直接调用项目 node_modules 里的命令；npm run commit则是你已经在 package.json 中配置了"commit": "cz"脚本之后的等价方式。三种方式本质最后都是调用 Commitizen 的 CLI 入口。
启动之前别忘了git add暂存你要提交的文件。Commitizen 的交互流程虽然不检查暂存区内容，但它在生成提交信息后执行的是git commit，如果暂存区为空，最终会得到nothing to commit的报错，体验很割裂。我一般是先git add .或按需要git add <file>，确认git status里列出了预期的文件，再跑npx cz。
4.2 六道必答题逐项解析
我把实际交互中最常见的六个问题逐一拆一下，这里填充的是我对每个字段的理解和填写建议，而且这些理解同样适用于你以后手动写提交信息。
第一问是提交类型选择。默认列表是：feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert。选错类型是很常见的事，划重点：新功能用feat，修 bug 用fix，CSS 调整这类纯粹改变外观但不改逻辑的用style，而重构逻辑、不改变外部行为和功能的是refactor。很多人会把style当成"调整了一些样式代码"来用，但其实按严格语义，样式相关的调整通常应该归到chore或随功能提交，style更多指"代码格式化、分号、空格"这类不改变运行逻辑的改动。
第二问是 scope 范围。它对应括号里的模块名，比如fix(login): ...中的login就是 scope，表示影响登录模块。scope 在可填可不填之间，我建议：如果这次改动影响明显集中的某个模块就填，如果跨了多个模块或者整体性比较强，留空完全没问题。不要为了填而填，随便编一个不存在的模块名比留空更难维护。
第三问是 subject 标题。它要求用祈使句，比如add user login endpoint而不是added user login endpoint或adding user login endpoint。原因是 Git 本身在交互式提交时推荐的就是命令式风格，这样整个git log读起来像"如果应用这个提交，它将……"，语义更加统一。标题同样不要加句号，保持精简，中文或英文都行，但建议一个项目里语言统一。英文小写开头在当前生态里最通用，中文则没有这个限制。
第四问是 body 详细描述。这里才是写背景、写细节的地方。值得写的内容包括：这个改动的动机是什么，解决了什么具体问题，做了哪些关键实现决策，以及有哪几个重点注意点。一个常见的误区是 body 写得太长，讲了一堆过程性废话。提交信息的正文不是周报，它是给未来读者看的，写清楚"为什么这么做"比写清楚"我一步步做了什么"更有价值。
第五问是是否包含破坏性变更。这里指 API 不兼容、数据库结构变化、配置项删除这类会破坏现有功能的情况。如果选了是，Commitizen 会额外要求你写一段破坏性说明，最终会作为BREAKING CHANGE出现在 footer 里。破坏性变更在语义化版本里意味着大版本号必须升主版本，所以这一问不能糊弄。我见过的绝大多数项目的隐含问题就是：升级依赖后接口行为变了，但谁都没填这一项，等别人上线才发现接不上了。
第六问是关联的 issue。它支持#123这种格式。填写后会生成Closes #123这样的 footer。要注意的是，很多代码托管平台通过这个Closes关键字在合并提交时自动关闭对应 issue，所以如果你不想在合并时自动关 issue，可以改用Related to #123这种描述，但 Commitizen 默认生成的肯定是Closes。团队协作时建议约定清楚：什么情况下用 closes，什么情况下只引用。
4.3 一个完整提交的生成过程演示
光说不练假把式，我们走一个具体的场景。假设你在开发一个用户系统，这次修复了 token 刷新并发请求时出现的竞态问题：
你在交互界面做以下选择：
- 提交类型：
fix - scope：填写
auth - subject：填写
fix token refresh race condition - body：填写
The token refresh request could fire multiple times before the first response returns, causing stale refresh token to be stored and the user to be logged out unexpectedly. - 破坏性变更：选择
No - 关联 issue：选择
Yes并填写#42
Commitizen 生成的完整提交信息如下：
fix(auth): fix token refresh race condition The token refresh request could fire multiple times before the first response returns, causing stale refresh token to be stored and the user to be logged out unexpectedly. Closes #42之后 Commitizen 会调用git commit真正完成提交。此时在git log --oneline看到的是abcd123 fix(auth): fix token refresh race condition，一眼就能看懂这次提交做了什么、影响哪个模块、关联哪个 issue。配合自动生成 Changelog 的流程，这条信息还能被工具直接提取为一条 release note。
4.4 交互过程中的实操心得
实际用久了你会发现，Commitizen 的交互流程也有值得微调的地方。比如 subject 的 87 字符限制，在写长项目名的模块时会很憋屈。我碰到过 scope 写一个很长的包名，结果 type 和 scope 占了大半行，subject 只剩十几个字符可写的情况。这种时候我的处理方式是把 scope 简写或直接留空，完整包名放到 body 里补充说明。
还有个细节，Commitizen 的交互在终端宽度不够的时候，个别选项列表会显示得很挤，容易看错。我一般把终端窗口拉宽一点再执行，避免因为视觉错乱选错类型。这在 CI 里不会发生，但在开发机上确实是个真实存在的体验问题。
5. 常见问题与排查技巧实录
5.1 配置与安装问题速查
我整理了这几类在真实项目里反复出现的问题，尤其是多人协作、多包管理工具并存的情况下，每个都值得收藏一份：
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
执行npx cz后只显示一行 Usage 就退出 | 项目里没初始化适配器 | 先执行npx commitizen init cz-conventional-changelog --save-dev --save-exact |
config.commitizen.path指向的包找不到 | 适配器被 pnpm 的 strict peer 机制拦截 | 手动把 path 改为cz-conventional-changelog作为包名，或检查.npmrc的 hoist 策略 |
全局安装了git cz却报 command not found | npm 全局 bin 目录不在 PATH 中 | 确认npm config get prefix对应的 bin 目录已加入 PATH |
npm run commit弹出代码编辑器 | npm script 环境里 cz 正常，但某一步远程配置影响了 git commit | 检查 core.editor 配置，必要时设置git config core.editor vi对比 |
| commitlint 报错但提交信息明明符合规范 | commitlint 配置和适配器类型列表不一致 | 统一commitlint.config.js的types与适配器types |
其中我自己踩过最大的坑就是 pnpm。pnpm 的 symlink 结构不像 npm 那样把所有依赖平铺在node_modules根目录下，cz-conventional-changelog有时会因为它依赖的某个包没被显式声明而找不到。后来我干脆在根目录的package.json里显式声明适配器包，并把config.commitizen.path写成cz-conventional-changelog包名而不是相对路径，才稳定下来。
5.2 使用与交互问题排查
交互流程本身相对稳定，但有几个使用层面的问题值得记录，它们更多是"怎么用才顺手"层面的：
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| 回答完所有问题，提交却失败并提示权限错误 | git commit 权限或 commit-msg 钩子报错 | 先单独跑git commit -m "test"看是否也有钩子问题，逐层排查 |
| 想修改前一次提交信息，但生成 commit 时发现已经推送到远端 | 提交后立刻 push 了 | 用git commit --amend配合cz重新生成信息，未推送前使用；已推送的走 revert 或 force push（需团队约定） |
| 交互问答里没有我想要的类型 | 适配器类型列表不满足需求 | 改用cz-customizable，在.cz-config.js里自定义 type 列表，或 fork 适配器 |
| 中文 title 在部分终端显示乱码 | 终端编码和 Git 编码不一致 | 建议团队统一用英文提交信息，或者统一设置终端 UTF-8 编码 |
这里我要提醒一句：Commitizen 生成的提交信息，本质是一条字符串，它不关心你用什么语言写 subject 和 body。你的团队用中文提交完全没问题。但需要考虑的问题是后续工具链，比如commitlint默认的类型检查和 changelog 生成工具对非英文文本的处理。我的经验是：subject 尽量用英文，body 里可以混写中文，两边不耽误。
5.3 排查思路：从报错信息出发
在社区里看别人报错，我发现 90% 的 Commitizen 问题集中在"适配器没配好"和"钩子冲突"两类。适配器没配好的典型特征就是：执行npx cz后没有出现交互问答，只是一闪而过或者打印 usage；钩子冲突的典型特征则是：问答流程顺利走完，最后git commit时被 commit-msg 钩子拦下，报出subject may not be empty这种 commitlint 错误。
排查的时候我的顺序固定是：先验证npx cz能不能进入交互界面，不行就查config.commitizen.path；能进交互但提交失败，就查 commit-msg 钩子；钩子本身配置没问题，就查 commitlint 规则是否需要针对 team 定制。这条路走下去，基本不会卡壳。
6. 实战经验与团队落地建议
6.1 提交信息自动生成 Changelog 和版本号
Commitizen 生成的标准提交信息，更大的价值在于它能被下游工具直接消费。我最常用的组合是standard-version，它根据git log中的feat、fix、BREAKING CHANGE类型自动判断是升主版本、次版本还是修订版本，并生成一份像样的 CHANGELOG.md。
在项目里配置standard-version之后，新版本发布基本是这样的流程：
git add . npx cz npx standard-version git push --follow-tags origin mainstandard-version会扫描从上一个 tag 以来的所有提交信息，从中提取feat、fix、BREAKING CHANGE、Closes #xx等标记，自动决定版本号并生成 changelog 内容。如果你想升某个指定的版本，可以加参数，比如--release-as minor。这意味着团队只要保证 Commitizen 交互阶段填写信息是准确的，从提交到版本发布之间几乎所有手工整理工作都不需要了。
6.2 团队落地的节奏与分寸
在团队里推 Commitizen，最大的敌人不是技术难度，而是积极性。强制所有人都立刻使用，往往会引发逆反心理，反而破坏流程推行。我见过推行成功的团队实际节奏是这样的：
第一个阶段，只在一个核心项目中引入 Commitizen，让小组里两三个积极尝鲜的人先用起来。第二个阶段，用 Husky + commitlint 在 commit-msg 钩子层做硬校验，但把规则放宽，先只检查 type 字段是否存在、subject 是否非空，逐步从不规范提交中收集实际错误样例再收紧。第三个阶段，等大家都体会到"自动生成 changelog"和"快速回溯变更"的好处之后，再统一要求 scope 必填或者 body 必填。
这个节奏的本质是先用收益牵引，再用约束兜底。Commitizen 本身是收益导向的工具，它让填写规范提交信息变得毫不费力；Husky 和 commitlint 才是约束导向的工具，它们守住底线。两者配合，不至于一开始就把团队逼出不适感。
6.3 进阶扩展：自定义适配器与 Monorepo 实践
如果团队对默认的cz-conventional-changelog提问文案不满意，比如你希望中文提示、希望新增一类自定义 type，用cz-customizable可以很快实现。安装之后写一份.cz-config.js：
module.exports = { types: [ { value: 'feat', name: 'feat: 新功能' }, { value: 'fix', name: 'fix: 修复 bug' }, { value: 'docs', name: 'docs: 文档变更' }, { value: 'refactor', name: 'refactor: 重构（不是新增功能也不是修复）' } ], allowBreakingChanges: ['feat', 'fix'], subjectLimit: 100 };这种配置在需要多语言提示、或者想精简 type 列表的团队里很实用。需要注意的一点是：如果你改了types列表，commitlint.config.js里的规则也得同步改，否则就出现了"Commitizen 允许的提交，commitlint 拒绝"的尴尬局面。我见过不止一个项目踩这个坑，改完.cz-config.js忘了同步 commitlint，最终白白浪费时间排查。
Monorepo 场景下，我的建议是在根目录配一套 Commitizen，子包不重复配置，避免仓库里出现多个config.commitizen路径导致执行乱套。配合pnpm时注意用pnpm dlx commitizen init这种形式初始化，手动在子包当作独立包发布时再考虑在子包内单独配置。
6.4 最后谈谈我个人对规范提交的体会
这套工具链我前前后后用了多年，从最开始嫌弃"多问几个问题浪费时间"，到现在已经完全离不开。最大的心得倒不是某个具体的配置项，而是一个观念转变：提交信息不是写给 Git 看的元数据，而是写给未来的自己和其他协作者的便签。Commitizen 的交互式提交真正解决的不是"格式规范"问题，而是"格式成本"问题——过去你要记住一堆规则，现在只需要在问答里如实选择、如实填写。再配合 commitlint 兜底，团队里用不用 Commitizen 已经不再是个可选项，因为不用它，你几乎写不出能通过校验的提交信息。
如果你正准备在团队里推行这套流程，我建议从小范围开始，先让两三个人用起来，产生几条高质量提交信息作为范例，其他人看到git log的整洁度自然会被吸引。工具可以快速配置，习惯才是最难养成的。一旦大家从交互式提交里获得了"可检索、可回溯、可自动生成 changelog"的反馈，这套流程基本上就不需要你再操心了。
