发布管理

规范的版本发布流程能让团队更自信地发布软件，也让用户更容易理解版本变化。

语义化版本（SemVer）

语义化版本规范（Semantic Versioning） 是版本号管理的行业标准：

v主版本号.次版本号.修订号
v MAJOR . MINOR . PATCH

版本号	触发条件	示例
MAJOR	不兼容的 API 变更	v1.0.0 → v2.0.0
MINOR	向后兼容的新功能	v1.0.0 → v1.1.0
PATCH	向后兼容的 Bug 修复	v1.0.0 → v1.0.1

预发布版本：

v1.0.0-alpha.1    内部测试版
v1.0.0-beta.2     公开测试版
v1.0.0-rc.1       候选发布版（Release Candidate）

使用 Tag 管理版本

Git 标签用于标记每个发布的版本：

# 确保在最新的 main 分支
git switch main
git pull origin main

# 创建附注标签（推荐）
git tag -a v1.2.0 -m "Release v1.2.0

## 新功能
- 添加用户头像上传功能
- 支持暗色主题

## Bug 修复
- 修复登录页面内存泄露
- 修复移动端布局问题"

# 推送标签
git push origin v1.2.0

# 在 GitHub 上创建 Release（基于 Tag）
gh release create v1.2.0 \
  --title "v1.2.0" \
  --notes-file CHANGELOG.md \
  --latest

CHANGELOG 生成

手动维护 CHANGELOG

遵循 Keep a Changelog 规范：

# Changelog

所有重要的版本变更都记录在此文件中。

格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
版本管理遵循 [语义化版本规范](https://semver.org/)。

## [未发布]

## [1.2.0] - 2026-03-09

### 新增
- 用户头像上传功能
- 暗色主题支持

### 修复
- 修复登录页面内存泄露
- 修复移动端布局问题

### 废弃
- 弃用 `/api/v1/users` 接口，将在 v2.0.0 移除

## [1.1.0] - 2026-02-01

...

自动生成 CHANGELOG

基于 Conventional Commits 规范，可以自动生成 CHANGELOG：

# 使用 conventional-changelog
npm install -g conventional-changelog-cli

# 生成 CHANGELOG（追加模式）
conventional-changelog -p angular -i CHANGELOG.md -s

# 使用 release-please（GitHub Actions）
# .github/workflows/release.yml

GitHub Actions 自动发布：

# .github/workflows/release.yml
name: Release
on:
  push:
    tags: ['v*']

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          generate_release_notes: true  # 自动生成发布说明

Release Branch 管理

对于需要维护多个版本的项目：

创建发布分支

# 从 develop 创建发布分支
git switch develop
git switch -c release/1.3.0

# 在发布分支上只做 bug 修复和版本号更新
npm version minor --no-git-tag-version  # 更新 package.json 版本号
git add package.json
git commit -m "chore: bump version to 1.3.0"

# 发布准备完成后
# 1. 合并到 main 并打 tag
git switch main
git merge --no-ff release/1.3.0 -m "Merge release 1.3.0"
git tag -a v1.3.0 -m "Release v1.3.0"
git push origin main --tags

# 2. 合并回 develop（包含 bug 修复）
git switch develop
git merge --no-ff release/1.3.0 -m "Merge release 1.3.0 back to develop"
git push origin develop

# 3. 删除发布分支
git branch -d release/1.3.0

Hotfix 流程

线上 bug 紧急修复：

# 1. 从线上版本标签创建 hotfix 分支
git switch main
git switch -c hotfix/1.2.1

# 修复 bug
git commit -m "fix: 修复用户无法登录的紧急问题"

# 2. 更新版本号
npm version patch --no-git-tag-version
git add package.json
git commit -m "chore: bump version to 1.2.1"

# 3. 合并到 main 并打 tag
git switch main
git merge --no-ff hotfix/1.2.1 -m "Merge hotfix 1.2.1"
git tag -a v1.2.1 -m "Hotfix v1.2.1: 修复用户登录问题"
git push origin main --tags

# 4. 合并到 develop
git switch develop
git merge --no-ff hotfix/1.2.1 -m "Merge hotfix 1.2.1 into develop"
git push origin develop

# 5. 清理
git branch -d hotfix/1.2.1

自动化发布流程

使用 release-please（推荐）

release-please 基于 Conventional Commits 自动创建 Release PR：

# .github/workflows/release-please.yml
name: release-please
on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        with:
          release-type: node

工作流程：

1. 合并到 main 的 Conventional Commits 会被分析
2. release-please 自动创建/更新一个 Release PR
3. Release PR 包含自动生成的 CHANGELOG 和版本号更新
4. 合并 Release PR 后，自动创建 Tag 和 GitHub Release

使用 npm version（Node.js 项目）

# 更新版本、创建 commit 和 tag（一步完成）
npm version patch   # 1.0.0 → 1.0.1
npm version minor   # 1.0.0 → 1.1.0
npm version major   # 1.0.0 → 2.0.0

# 推送代码和标签
git push && git push --tags

总结

步骤	操作
确定版本号	遵循 SemVer 规范
准备发布	更新 CHANGELOG，测试验证
创建标签	git tag -a v<version> -m "..."
推送标签	git push origin v<version>
创建 Release	GitHub/GitLab Release 页面或 CLI

规范的发布流程不仅让用户能理解版本变化，也让团队在出现问题时能快速定位和回滚。结合自动化工具（release-please、conventional-changelog），可以大幅降低发布管理的手动成本。