开源项目的自动化发版实践

维护开源项目时，版本发布常常占用大量时间。手动整理提交记录、更新版本号、生成变更日志这些重复操作，不仅容易出错，还会分散开发者对核心功能的注意力。

传统发版流程的痛点

实际项目中常见的几个问题：

版本号管理混乱
团队成员对何时升级主版本/次版本/修订版缺乏统一标准。有人觉得修复了一个bug就该升次版本，有人坚持只有新功能才能升主版本。

变更日志不完整
手动整理的更新说明经常漏掉重要改动。上周刚发现某个依赖升级导致兼容性问题，结果 changelog 里根本没提这次升级。

小修复难以及时发布
因为发版流程太麻烦，很多紧急修复要攒够一堆改动才一起发布。有次线上有个严重bug，我们拖了三天才发新版。

自动化发版的核心思路

我们采用了 conventional commits 规范配合 semantic-release 工具，实现：

1. 提交信息规范：type(scope): description 格式（如 fix(auth): resolve token refresh issue）
2. CI自动解析提交记录判断版本升级类型
3. 自动生成 changelog 并推送至包管理器

sequenceDiagram
    actor Maintainer as 维护者
    participant GitHub as GitHub仓库
    participant CI as GitHub Actions
    participant NPM as NPM Registry

    Maintainer->>GitHub: 合并PR (commit: fix(core): auto-reconnect)
    GitHub->>CI: 触发CD流水线
    CI->>CI: 解析Git历史获取新增commit
    CI->>CI: 按conventional规范分析版本变动
    CI->>CI: 更新package.json并创建Git tag
    CI->>CI: 聚合生成CHANGELOG.md
    CI->>NPM: npm publish发布新版本
    CI->>GitHub: 提交tag和更新后的changelog

实践中的关键配置

提交规范强制检查

在项目根目录添加 .commitlintrc.json：

{
  "extends": ["@commitlint/config-conventional"],
  "rules": {
    "type-enum": [2, "always", ["feat", "fix", "docs", "chore", "refactor"]]
  }
}

配合 husky 在本地提交时拦截不规范格式：

# .husky/commit-msg
npx --no -- commitlint --edit "$1"

发布策略优化

初期我们也遇到频繁发布引发的问题：

• 用户抱怨依赖版本跳动太快
• 小修复反而增加了测试负担

后来调整为：

1. main分支日常开发
2. 每周五从main创建release分支
3. 由release分支触发正式发版

需要注意的风险点

权限安全
CI/CD 使用的 NPM token 需要限制权限，最好配合 MFA 验证。有次同事的账号被盗，幸好我们的发布流程设置了双重审核。

历史追溯困难
完全自动化的 changelog 有时会丢失上下文。现在我们会在关键 PR 中手动补充说明，比如：

## Breaking Change
- 重构了认证模块，旧版 SDK 不再兼容

工具链依赖
semantic-release 的插件配置需要持续维护。上个月因为某个插件更新导致发布失败，花了半天才定位到是 @semantic-release/changelog 版本不兼容。

实际效果对比

现在团队成员可以更专注于功能开发，上周上线的新特性从合并到发布只用了 15 分钟。当然，前期配置花了不少时间，但长期来看确实解放了生产力。