⚠️ Alpha内测版本警告：此为早期内部构建版本，尚不完整且可能存在错误，欢迎大家提Issue反馈问题或建议
Vibe Vibe

主题

8.3.4 自动生成更新日志——CHANGELOG 生成 ​

规范的提交信息不只是为了好看——它能让工具自动生成发布日志。

为什么需要 CHANGELOG ​

CHANGELOG 是项目版本更新的"说明书"：

  • 用户知道新版本有什么变化
  • 开发者知道引入了哪些 breaking change
  • 运维知道是否需要特殊的升级步骤

工具选择 ​

工具特点适用场景
conventional-changelog老牌工具手动触发生成
standard-version一站式版本管理中小型项目
semantic-release全自动发布CI/CD 集成
changesetsMonorepo 友好多包项目

standard-version 使用 ​

安装 ​

bash
pnpm add -D standard-version

配置 package.json ​

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

使用流程 ​

bash
# 根据提交历史自动决定版本号
pnpm release

# 指定版本类型
pnpm release:minor  # 1.0.0 -> 1.1.0
pnpm release:major  # 1.0.0 -> 2.0.0

# 首次发布
pnpm release -- --first-release

执行后会：

  1. 分析提交历史，确定版本号
  2. 更新 package.json 的 version
  3. 生成/更新 CHANGELOG.md
  4. 创建版本提交和 tag

版本号规则 ​

基于 Semantic Versioning：

提交类型版本变更示例
featminor1.0.0 → 1.1.0
fixpatch1.0.0 → 1.0.1
BREAKING CHANGEmajor1.0.0 → 2.0.0

CHANGELOG 输出示例 ​

markdown
# Changelog

## [1.2.0](https://github.com/user/repo/compare/v1.1.0...v1.2.0) (2024-01-15)

### Features

* **auth:** 添加 Google OAuth 登录 ([#123](https://github.com/user/repo/issues/123)) ([abc1234](https://github.com/user/repo/commit/abc1234))
* **ui:** 支持暗黑模式切换 ([def5678](https://github.com/user/repo/commit/def5678))

### Bug Fixes

* **api:** 修复分页查询参数解析错误 ([#145](https://github.com/user/repo/issues/145)) ([ghi9012](https://github.com/user/repo/commit/ghi9012))

## [1.1.0](https://github.com/user/repo/compare/v1.0.0...v1.1.0) (2024-01-01)

### Features

* 初始化项目结构 ([jkl3456](https://github.com/user/repo/commit/jkl3456))

自定义配置 ​

创建 .versionrc.json：

json
{
  "types": [
    { "type": "feat", "section": "Features" },
    { "type": "fix", "section": "Bug Fixes" },
    { "type": "perf", "section": "Performance" },
    { "type": "refactor", "section": "Refactoring", "hidden": true },
    { "type": "docs", "section": "Documentation", "hidden": true },
    { "type": "style", "hidden": true },
    { "type": "chore", "hidden": true },
    { "type": "test", "hidden": true },
    { "type": "build", "hidden": true },
    { "type": "ci", "hidden": true }
  ],
  "commitUrlFormat": "https://github.com/user/repo/commit/{{hash}}",
  "compareUrlFormat": "https://github.com/user/repo/compare/{{previousTag}}...{{currentTag}}"
}

CI/CD 集成 ​

GitHub Actions 自动发布 ​

yaml
# .github/workflows/release.yml
name: Release

on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: pnpm install

      - name: Release
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          pnpm release
          git push --follow-tags origin main

semantic-release（进阶） ​

适合完全自动化的项目：

bash
pnpm add -D semantic-release @semantic-release/changelog @semantic-release/git

配置 .releaserc.json：

json
{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/git",
    "@semantic-release/github"
  ]
}

最佳实践 ​

  1. 保持提交规范：CHANGELOG 质量取决于提交信息质量
  2. 关联 Issue：让变更可追溯
  3. 标记 Breaking Change：让用户知道如何升级
  4. 定期发布：避免 CHANGELOG 过长

AI 协作指南 ​

示例 Prompt：

"请根据以下 Git 提交历史，帮我生成一份 CHANGELOG：

  • feat(auth): 添加微信登录
  • fix(api): 修复用户查询分页问题
  • feat(ui): 新增用户设置页面
  • perf(database): 优化查询性能"

验收清单 ​

  • [ ] 安装并配置 standard-version
  • [ ] 能执行 release 命令生成 CHANGELOG
  • [ ] 理解版本号自动变更规则
  • [ ] 可选：配置 CI 自动发布