深入理解conventional-changelog工具：自动化生成项目变更日志

什么是conventional-changelog

conventional-changelog是一个基于Git提交元数据自动生成变更日志(CHANGELOG)的工具。它通过分析项目的Git提交历史，按照特定的提交约定格式，自动生成结构清晰、分类明确的变更日志文档。

核心优势

1. 自动化程度高：只需简单配置，即可自动生成专业级别的变更日志
2. 约定式提交支持：完美支持Angular等流行的提交约定规范
3. 高度可定制：提供多种预设配置，也可完全自定义输出格式
4. 智能过滤：自动忽略回滚提交等无关内容
5. 版本关联：能够按版本范围生成变更日志

安装与基础使用

安装方式

# 使用pnpm安装
pnpm add conventional-changelog

# 使用yarn安装
yarn add conventional-changelog

# 使用npm安装
npm i conventional-changelog

基本命令

生成自上次发布以来的变更日志（不会覆盖现有日志）：

conventional-changelog -p angular

生成所有历史变更日志（会覆盖现有日志）：

conventional-changelog -p angular -r 0

推荐的工作流程

1. 完成代码修改并提交
2. 确保所有测试通过
3. 更新package.json中的版本号
4. 运行conventional-changelog生成变更日志
5. 提交package.json和CHANGELOG.md文件
6. 创建版本标签
7. 推送代码和标签

与npm version集成

在package.json中添加以下脚本可以实现更自动化的流程：

{
  "scripts": {
    "version": "conventional-changelog -p angular && git add CHANGELOG.md"
  }
}

配合.npmrc配置可以实现更完整的自动化发布流程：

tag-version-prefix=""
message="chore(release): %s :tada:"

预设配置

conventional-changelog提供了多种预设配置，以适应不同项目的需求：

• angular：遵循Angular提交规范
• atom：适用于Atom编辑器项目
• codemirror：CodeMirror编辑器风格
• conventionalcommits：标准约定式提交
• ember：Ember.js项目风格
• eslint：ESLint项目风格
• express：Express框架风格
• jquery：jQuery项目风格
• jshint：JSHint工具风格

JavaScript API详解

conventional-changelog提供了丰富的JavaScript API，可以实现更灵活的集成：

import { ConventionalChangelog } from 'conventional-changelog'

// 创建实例并配置
const generator = new ConventionalChangelog()
  .readPackage()  // 读取package.json
  .loadPreset('angular')  // 加载angular预设

// 输出到标准输出
generator
  .writeStream()
  .pipe(process.stdout)

// 或者使用异步迭代器
for await (const chunk of generator.write()) {
  console.log(chunk)
}

核心API方法

1. loadPreset()：加载预设配置
2. config()：直接设置配置对象
3. readPackage()：读取package.json文件
4. package()：直接设置package信息
5. readRepository()：读取Git仓库信息
6. repository()：直接设置仓库信息
7. options()：设置生成选项
8. context()：设置写入上下文
9. tags()：设置版本标签参数
10. commits()：设置提交参数
11. writer()：设置写入选项
12. write()：生成变更日志
13. writeStream()：生成变更日志流

最佳实践建议

1. 统一提交规范：团队应采用一致的提交消息格式，推荐使用Angular提交约定
2. 版本控制集成：将变更日志生成集成到版本发布流程中
3. 定期更新：建议每个版本发布时都更新变更日志
4. 代码审查：将CHANGELOG.md文件纳入代码审查范围
5. 自动化测试：可以考虑为变更日志生成编写自动化测试

常见问题解决

1. 生成的日志不完整：检查是否使用了正确的预设，提交消息是否符合规范
2. 版本范围不正确：确认tags()参数设置是否正确
3. 特殊提交被忽略：检查transformCommit函数是否过滤了有效提交
4. 日期格式不符预期：自定义formatDate函数进行调整

通过合理配置和使用conventional-changelog，项目可以轻松维护专业级的变更日志，大大提高开发效率和项目透明度。