根本原因是git cz命令依赖commitizen cli及适配器模块（如cz-conventional-changelog）的正确安装与路径识别：全局安装commitizen后需确保cz可执行，且项目本地必须安装对应adapter（pnpm用户尤其需-dev安装），vscode还需配置commitizen.defaultpath或通过.czrc/package.json指定path，否则提示“cannot find module”。
Commitizen安装后git cz命令不生效
根本原因是git cz不是全局可用的别名，而是通过commitizen包提供的 CLI 工具，需确保 Node.js 环境下正确安装并加入 PATH。
- 全局安装：
npm install -g commitizen（推荐）或yarn global add commitizen - 验证是否可用：
cz --version能输出版本号，说明 CLI 可用；git cz本质是 Git 调用cz，依赖 Git 的 alias 机制，但现代 Commitizen 默认自动注册该 alias，无需手动配git config --global alias.cz 'cz' - 常见坑：使用 pnpm 或 nvm 切换 Node 版本后，全局 bin 目录可能未被 shell 加载，执行
which cz返回空时，需检查$PATH是否包含对应 global bin 路径（如~/.pnpm-global/bin或$(npm config get prefix)/bin）
VSCode 中点击“提交”按钮仍走原生 Git 提交流程
VSCode 默认的 Source Control 提交面板不识别 Commitizen，它只调用 git commit，必须显式启用集成方案。
- 安装官方扩展：
Commitizen Support（作者：Knister Peter），非GitLens或其他 Git 增强插件自带的功能 - 启用后，在源代码管理视图中点击“+”号旁的下拉箭头，会出现
Commit using Commitizen选项；也可右键暂存文件 → 选择该选项 - 关键配置项：
commitizen.defaultPath（VSCode 设置项）应设为cz-conventional-changelog或你项目实际使用的 adapter（如cz-emoji），否则会报错Cannot find module 'cz-conventional-changelog' - 若项目根目录有
.czrc或package.json#config.commitizen，VSCode 插件会优先读取，此时commitizen.defaultPath可留空
提交时提示 Error: Cannot find module 'cz-conventional-changelog'
这是 adapter 模块缺失，不是 Commitizen 本身没装好，而是具体用于生成提交模板的适配器未安装。
- 在项目根目录运行：
npm install --save-dev cz-conventional-changelog（或yarn add -D cz-conventional-changelog） - 确认
package.json中存在如下配置之一："config": { "commitizen": { "path": "./node_modules/cz-conventional-changelog" } }或"commitizen": { "path": "cz-conventional-changelog" } - 注意路径写法：若用相对路径（如
./node_modules/xxx），必须确保该模块确实在node_modules下；若用短名（如cz-conventional-changelog），则要求该模块已全局或本地安装且可被 require 到 - pnpm 用户特别注意：由于硬链接隔离机制，
cz-conventional-changelog必须安装在项目本地（-D），不能仅靠全局安装
VSCode 提交面板里选了 type 和 scope，但生成的 message 缺少 body 或 breaking change 提示
Commitizen 的交互式 CLI 会根据 adapter 实现决定字段是否必填、是否展开，VSCode 插件只是调用它，行为一致 —— 但默认的 cz-conventional-changelog 确实跳过 body 和 breaking change，除非你主动输入。
- 想强制填写 body？换用更严格的 adapter，比如
cz-customizable，配合自定义配置文件控制字段必填性 - 当前流程中按
Enter直接跳过 body 是设计如此，并非 bug；breaking change 需要你在 prompt 中明确输入!符号（如feat(api)!: drop legacy endpoints）才会触发 - VSCode 插件不会修改原始 adapter 的交互逻辑，所有字段展示顺序、是否跳过，均由 adapter 的
prompts.js决定，无法通过 VSCode 设置绕过
cz 找不到 adapter 的错误几乎都源于此。
