Vue 3 项目的协作效率，很大程度上取决于 Git 提交信息是否可读。如果每个成员都按照自己的习惯填写 commit message，比如 update、fix、修改，那么一段时间后，提交历史就变成一锅粥，发布变更日志、定位问题版本、回滚代码都会变得非常困难。Commitizen 通过交互式问答将提交信息规范成统一的 Conventional Commits 格式，Conventional Changelog 则可以直接从这些规范提交中提取信息生成 CHANGELOG.md。
本文将以 Vue 3 项目为例，逐步配置 Commitizen 和 Conventional Changelog，并加入 commitlint 校验，形成一套完整的工程化提交闭环。
为什么 Vue 3 需要 Conventional Commits 规范
Conventional Commits 是一套基于提交信息的轻量约定，核心格式为 <type>(<scope>): <subject>。其中 type 表示提交类型，常见的有 feat（新功能）、fix（缺陷修复）、docs（文档变更）、style（代码格式，不影响逻辑）、refactor（重构）、test（测试相关）和 chore（构建或辅助工具变更）。scope 是可选的作用范围，例如 Vue 3 项目中的 router、store、component 等，subject 则是对本次提交的简短描述。
Vue 3 使用组合式 API、模块化路由与状态管理，一个功能往往涉及多个目录。如果不加约束，某个提交可能只写一个 fix，完全看不出是修了路由守卫还是修复了 Pinia 里的数据持久化问题。采用 Conventional Commits 后，所有提交信息都带类型前缀和可选范围，阅读历史时能快速过滤出某类变更，也为自动生成 changelog 和语义化版本号提供了结构化数据来源。
另一个实际好处是降低 Code Review 成本。当提交信息格式固定后，审查者无需在杂乱信息中猜测改动意图，而发布负责人也可以根据 feat 和 fix 的分布判断下一个版本是 minor 还是 patch。对于长期维护的 Vue 3 应用，这套规范是团队协作的隐形基建。
安装 Commitizen 并初始化配置
Commitizen 是一个让提交信息填写变得可交互的工具。它不会改变 Git 本身，而是在执行提交时启动一个问答流程，询问提交类型、作用范围、简短描述、详细说明和是否包含破坏性变更，最后拼装成符合 Conventional Commits 的完整 message。在 Vue 3 项目根目录下，首先安装 commitizen 和官方适配器 cz-conventional-changelog。
npm install --save-dev commitizen cz-conventional-changelog
安装完成后，需要在 package.json 中增加一段 config 配置，声明使用哪个适配器。同时把 cz 命令挂到自定义脚本上，方便团队成员统一使用 npm run commit 触发交互式提交，而不用记住 npx 参数。
{
"scripts": {
"commit": "cz"
},
"config": {
"commitizen": {
"path": "cz-conventional-changelog"
}
}
}
此时运行 npm run commit，终端会依次询问：选择提交类型、输入影响范围、填写简短描述、填写详细描述、确认是否有破坏性变更以及是否关联 issue。完成所有步骤后，Commitizen 会生成一条类似 feat(login): add phone number validation 的规范提交信息，并自动执行 git commit。如果只想体验问答流程但不想真正提交，可以运行 npx cz --dry-run 预览结果。
需要注意的是，Commitizen 本身只负责生成规范信息，并不会阻止开发者使用普通 git commit -m 绕过它。因此后续还需要引入 commitlint 做强制校验，确保所有提交都符合规范。
配置 Conventional Changelog 自动生成变更日志
Conventional Changelog 是一个命令行工具，它会扫描 Git 提交历史，筛选出符合 Conventional Commits 格式的记录，按类型分组生成结构化的 CHANGELOG.md 文件。默认情况下，它会根据 angular 预设规则解析 feat、fix、perf 等类型，并自动加上版本号、日期和提交链接信息。对于 Vue 3 项目，只需要安装 conventional-changelog-cli 即可使用。
npm install --save-dev conventional-changelog-cli
安装后在 package.json 的 scripts 中增加一个 changelog 命令。常用参数中，-p angular 指定预设风格，-i CHANGELOG.md 表示输出到当前目录的 CHANGELOG.md 文件，-s 表示同时把生成的内容写入文件并输出到终端，方便检查。
{
"scripts": {
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
}
}
执行 npm run changelog 后，项目根目录会生成 CHANGELOG.md，内容按照版本分组，每个组内包含 Features、Bug Fixes 等小节，每条记录对应一条规范提交。如果之前的提交历史中已经存在版本标签（例如 v1.0.0、v1.1.0），工具会只生成最新一个标签之后的变更。若想从第一次提交开始重建完整日志，可以追加 -r 0 参数，命令变为 conventional-changelog -p angular -i CHANGELOG.md -s -r 0。
生成 changelog 的前提是提交信息必须足够规范。如果历史中存在大量 update、修改等非结构化信息，Conventional Changelog 无法解析出有效条目，生成的日志会缺失很多内容。因此通常先规范提交流程，再逐步引入自动生成日志，这样才能保证产出质量。
用 commitlint 与 husky 强制校验提交信息
Commitizen 只是降低了填写规范信息的门槛，并没有从机制上阻止不合规提交。要让 Vue 3 团队的每个成员都遵守规则，需要借助 commitlint 对 commit message 做自动校验。commitlint 提供了多个配置预设，@commitlint/config-conventional 就是专门匹配 Conventional Commits 规范的规则集。
npm install --save-dev @commitlint/cli @commitlint/config-conventional husky
接着在项目根目录创建 commitlint.config.js，内容非常简单，直接继承 conventional 预设即可。
module.exports = {
extends: ['@commitlint/config-conventional']
};
为了让校验发生在提交动作执行之前，需要配合 husky 管理 Git 钩子。先执行 npx husky install 初始化 husky，然后添加 commit-msg 钩子，在用户输入提交信息后立即调用 commitlint 进行检查。
npx husky install npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1'
配置完成后，可以试着执行一条不符合规范的提交，例如 git commit -m "update code"，终端会立刻报错并提示 type 字段缺失或无效。只有使用 npm run commit 生成的规范信息才能通过校验。这样就把 Commitizen 和 commitlint 结合起来，既提供了便利的填写方式，又保证了强制约束。
还需要注意，clone 仓库后 husky 钩子不会自动安装。建议在 package.json 的 scripts 中增加 prepare 脚本，内容为 husky install，这样每次执行 npm install 时都会自动初始化钩子，避免新成员提交时校验失效。
Vue 3 项目中的完整示例与常见问题
下面是一个 Vue 3 项目集成完 Commitizen、Conventional Changelog、commitlint 和 husky 后的 package.json 核心片段。scripts 中包含了 commit、changelog 和 prepare 三个命令，config 中指定了 Commitizen 适配器。
{
"scripts": {
"commit": "cz",
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
"prepare": "husky install"
},
"config": {
"commitizen": {
"path": "cz-conventional-changelog"
}
},
"devDependencies": {
"@commitlint/cli": "^18.0.0",
"@commitlint/config-conventional": "^18.0.0",
"commitizen": "^4.3.0",
"conventional-changelog-cli": "^3.0.0",
"cz-conventional-changelog": "^3.3.0",
"husky": "^8.0.0"
}
}
实际提交流程中，开发人员修改完代码后运行 npm run commit，根据提示选择类型为 feat，输入 scope 为 router，填写简短描述 add dynamic route support，最终生成提交信息 feat(router): add dynamic route support。随后 husky 会调用 commitlint 校验，通过后提交完成。发布新版本时运行 npm run changelog，CHANGELOG.md 会自动更新，列出本次版本中所有新功能和修复。
实践中有几个高频问题需要特别注意。首先是 scope 的括号，Conventional Commits 要求使用小括号，feat[router] 或 feat router 都会被 commitlint 拦截。其次是提交类型，fixed、bugfix 并不是标准类型，必须使用 fix。第三是 changelog 只生成最新标签之后的日志，如果项目还没有打标签，或者想重建全部历史，要加上 -r 0 参数。第四是 husky 钩子未生效，通常是因为没有配置 prepare 脚本或没有执行过 npx husky install。确认这些细节后，Vue 3 项目的提交规范和自动化变更日志就能稳定运行。
CommitizenConventional ChangelogVue 3修改时间：2026-08-21 06:42:17