git怎么使用conventional-changelog生成变更日志

Git实战：利用Conventional Changelog自动生成规范变更日志

目录导读

前言：为什么需要规范的变更日志？
Conventional Changelog是什么？
核心工具与环境配置
实战：从零配置到生成日志
自定义配置与高级用法
集成到工作流的最佳实践
常见问题与解决方案
总结与资源推荐

前言：为什么需要规范的变更日志？

在软件开发过程中,变更日志（CHANGELOG）是记录项目版本更新内容的重要文档，手动维护变更日志往往面临更新不及时、格式混乱、遗漏关键变更等问题，特别是团队协作时，缺乏规范的提交信息会导致日志生成困难，历史追溯成本增高。

规范的提交信息配合自动化工具,能够实现：

自动生成清晰可读的变更日志
简化版本管理和发布流程
遵循语义化版本控制（SemVer）
提高团队协作效率和代码质量

本文将详细介绍如何使用Git配合Conventional Changelog生态系统，自动化生成专业级变更日志。

Conventional Changelog是什么？

Conventional Changelog是一套基于约定式提交（Conventional Commits）规范的自动化工具链，其核心思想是通过规范Git提交信息的格式，使工具能够自动解析提交历史，生成结构化的变更日志。

约定式提交的基本格式：

<类型>[可选的作用域]: <描述>
[可选的脚注]

常用提交类型：

feat: 新功能（对应MINOR版本）
fix: 错误修复（对应PATCH版本）
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 构建过程或辅助工具变更

完整的规范可参考官方文档：ww.jxysys.com/conventional-commits

核心工具与环境配置

环境准备

确保已安装：

Node.js (12.x或更高版本)
Git (2.x或更高版本)
npm或yarn包管理器

关键工具介绍

commitizen: 交互式提交工具，引导开发者编写规范提交信息
cz-conventional-changelog: Commitizen适配器，提供约定式提交规范
conventional-changelog-cli: 命令行工具，用于生成变更日志
standard-version: 自动化版本管理和变更日志生成工具

实战：从零配置到生成日志

步骤1：初始化项目

# 在项目根目录执行
npm init -y

步骤2：安装必要依赖

# 全局或局部安装（推荐项目局部安装）
npm install --save-dev commitizen cz-conventional-changelog

步骤3：配置Commitizen

在package.json中添加：

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

步骤4：安装并配置Conventional Changelog CLI

npm install --save-dev conventional-changelog-cli

在package.json中添加生成脚本：

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

步骤5：使用规范提交

# 使用commitizen代替git commit
npm run commit
# 或直接使用npx
npx git-cz

交互界面将引导你填写：

选择变更类型
填写影响范围（可选）
输入简短描述
提供详细说明（可选）
列出破坏性变更（如有）
关联Issue（可选）

步骤6：生成变更日志

# 生成所有版本的变更日志
npm run changelog
# 生成特定版本后的变更
npx conventional-changelog -p angular -i CHANGELOG.md -s

自定义配置与高级用法

自定义配置文件

创建.changelogrc.js文件：

module.exports = {
  "types": [
    {"type": "feat", "section": "新功能"},
    {"type": "fix", "section": "错误修复"},
    {"type": "perf", "section": "性能优化"},
    {"type": "docs", "section": "文档更新"}
  ],
  "releaseCommitMessageFormat": "chore(release): {{currentTag}}"
}

使用standard-version自动化流程

npm install --save-dev standard-version

在package.json中添加：

{
  "scripts": {
    "release": "standard-version"
  }
}

发布新版本时只需：

npm run release -- --release-as major  # 主版本
npm run release -- --release-as minor  # 次版本
npm run release -- --release-as patch  # 修订版本

集成Husky强制提交规范

npm install --save-dev husky @commitlint/cli @commitlint/config-conventional

创建commitlint.config.js：

module.exports = {
  extends: ['@commitlint/config-conventional']
};

配置Husky：

{
  "husky": {
    "hooks": {
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  }
}

集成到工作流的最佳实践

Git分支策略结合

main/master分支: 仅包含规范提交，用于自动生成日志
develop分支: 开发分支，定期合并到主分支
feature分支: 功能开发，提交信息遵循规范

CI/CD流水线集成

在GitHub Actions中配置：

name: Generate Changelog
on:
  push:
    branches: [main]
jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Generate Changelog
        run: |
          npm install
          npm run changelog
      - name: Commit CHANGELOG
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add CHANGELOG.md
          git commit -m "docs(changelog): update changelog"
          git push

多包项目管理

使用Lerna配合Conventional Changelog：

npx lerna init
npx lerna add commitizen --dev
npx lerna add conventional-changelog-cli --dev

常见问题与解决方案

Q1: 如何为现有项目添加变更日志？

A: 使用--first-release选项生成初始日志：

npx conventional-changelog -p angular -i CHANGELOG.md -s -r 0

Q2: 提交信息不规范导致日志生成失败怎么办？

A: 使用以下工具检查和修复：

# 检查最后几次提交
npx commitlint --from=HEAD~3 --to=HEAD
# 交互式重写提交历史
git rebase -i HEAD~5

Q3: 如何自定义日志模板？

A: 创建自定义模板文件template.hbs：


{{#each commitGroups}}
### {{title}}
{{#each commits}}
* {{subject}}
{{/each}}
{{/each}}

然后使用：

npx conventional-changelog -p angular -t ./template.hbs -i CHANGELOG.md -s

Q4: 如何处理破坏性变更？

A: 在提交信息正文中添加BREAKING CHANGE:部分：

feat: 重构用户认证系统
BREAKING CHANGE: 移除了旧的API密钥认证方式，请使用新的OAuth2流程

Q5: 如何关联GitHub Issues？

A: 在提交信息脚注中引用：

fix: 修复登录页面崩溃问题
Closes #123, #456

总结与资源推荐

通过本文的指导,您已经掌握了使用Git和Conventional Changelog自动生成变更日志的完整流程，从环境配置、工具安装到工作流集成，这套方案能显著提升项目文档质量和团队协作效率。

关键优势总结：

自动化：减少手动维护成本
标准化：统一团队提交规范
可追溯：清晰记录每次变更
生态丰富：与主流工具链完美集成

扩展学习资源：

约定式提交官方规范：ww.jxysys.com/conventional-commits
Conventional Changelog项目：ww.jxysys.com/conventional-changelog
Semantic Versioning规范：ww.jxysys.com/semver
更多实战案例：ww.jxysys.com/changelog-examples

将规范化的提交习惯与自动化工具相结合,不仅能生成专业的变更日志，更能促进团队形成良好的开发规范，最终提升整个项目的可维护性和协作效率，从下一个项目开始，尝试引入这套工作流，体验自动化文档带来的便利吧！

正文