在 Vue 3 项目的迭代过程中，CHANGELOG 经常成为最容易被忽略的文件。开发阶段所有变更都集中在代码里，到了发版时才临时拼凑更新说明，不仅耗时，还容易遗漏关键改动。更麻烦的是，当多个成员并行开发时，手工整理提交记录几乎不可能还原真实的变更范围。

自动生成 CHANGELOG 的前提是让提交信息具备结构化特征。 Conventional Commits 规范定义了 fix、feat、chore 等提交类型，配合 breaking change 标记，可以让工具清晰地区分功能新增、缺陷修复和破坏性变更。 Vue 3 本身也是基于这种工作流维护版本，因此在项目里引入同样的机制会非常自然。

从工程化角度看，自动生成更新日志不只是节省时间，更重要的是让发版流程可重复、可审计。每次发布都能从 Git 历史中稳定产出相同的 CHANGELOG 条目，避免了人工遗漏或格式不一致的问题。对于维护多个分支或长期项目来说，这种一致性会显著降低沟通成本。

使用 conventional-changelog-cli 生成更新日志

最直接的方案是使用 conventional-changelog-cli。它读取当前项目的 Git 提交记录，根据提交信息中的类型和范围匹配预设规则，输出 markdown 格式的 CHANGELOG.md。以 Vue 3 + Vite 项目为例，先安装依赖：

npm install -D conventional-changelog-cli

接着在 package.json 中添加脚本。这里使用 angular 预设，它是最常见的提交规范，会生成包含 Features、Bug Fixes、Documentation 等分类的更新日志。命令中的 -p angular 指定预设，-i 指定输出文件，-s 表示在生成的日志上方保留之前的发布记录。

{
  "scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
  }
}

执行 npm run changelog 后，工具会扫描当前 Git 仓库中所有符合规范的提交，自动追加或覆盖 CHANGELOG.md 内容。如果还没生成过该文件，会创建新文件；如果已有历史记录，-s 参数会在文件顶部插入最新的 release 区块。需要注意的是，这个命令依赖当前 Git 标签来确定版本边界，因此最好在发版打标签之后运行。

结合 commitizen 与 husky 约束提交信息

自动生成的质量取决于提交信息是否规范。如果开发人员随意写提交说明，工具就无从分类，生成的日志也会变得混乱。为了从源头约束，可以引入 commitizen 和 husky。

先安装 commitizen 及其 Conventional Commits 适配器。安装后，在 package.json 中增加 config.commitizen 字段，指定适配器路径。此后开发者使用 git cz 命令代替 git commit，会进入交互式问答流程，选择类型、填写影响范围、描述和是否包含破坏性变更。

npm install -D commitizen cz-conventional-changelog

{
  "config": {
    "commitizen": {
      "path": "cz-conventional-changelog"
    }
  },
  "scripts": {
    "commit": "git-cz"
  }
}

交互式提交虽然降低了使用门槛，但并不能完全防止有人直接使用 git commit 绕过规范。补充一层 commitlint 配合 husky 的 Git 钩子可以强制校验提交信息。安装 @commitlint/cli、@commitlint/config-conventional 和 husky，然后添加 commit-msg 钩子来执行 commitlint。

npm install -D @commitlint/cli @commitlint/config-conventional husky
npx husky init

在项目根目录创建 commitlint.config.js，继承 conventional 配置。接着用 husky 添加 commit-msg 钩子，将提交信息交给 commitlint 检查。这样不符合规范的提交会被直接拒绝，从而保证 CHANGELOG 工具能够正确解析。

export default {
  extends: ['@commitlint/config-conventional']
};

echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg

需要注意，代码中的反斜杠和 $1 在 Windows 环境下可能需要调整，但原理一致。现在团队成员的提交信息格式统一后，后续自动生成 CHANGELOG 的成功率会大幅提升。

定制 CHANGELOG 输出与发版流程集成

默认的 angular 预设已经能满足大部分需求，但某些场景需要定制输出的分类和显示内容。可以在项目根目录创建 .versionrc 文件，覆盖默认配置。比如调整 types 数组来控制哪些提交类型出现在 CHANGELOG 中，或者通过 preMajor 和 releaseCommitMessageFormat 控制初始版本与发版提交的格式。

{
  "types": [
    { "type": "feat", "section": "Features" },
    { "type": "fix", "section": "Bug Fixes" },
    { "type": "docs", "section": "Documentation" },
    { "type": "refactor", "section": "Code Refactoring" },
    { "type": "perf", "section": "Performance Improvements" }
  ]
}

如果不想只生成 CHANGELOG，还希望自动升级 package.json 版本号、打 Git 标签、提交发版记录，可以考虑 standard-version 或 release-it。standard-version 基于 conventional-changelog 封装，执行一条命令就能完成版本号计算、CHANGELOG 生成、Git 提交和标签创建。安装后把发布脚本改为 standard-version 即可。

npm install -D standard-version

{
  "scripts": {
    "release": "standard-version",
    "release:minor": "standard-version --release-as minor",
    "release:patch": "standard-version --release-as patch"
  }
}

在 CI 环境中，可以设置一个发布流水线，当合并到主分支且测试通过后自动执行 npm run release。因为 standard-version 会自动创建带注释的 Git 标签，方便后续追踪版本。需要注意的是，CI 需要配置正确的 Git 用户信息，并拥有推送权限，否则发布步骤会因无法提交而中断。