release-please 评测：用 Conventional Commits 自动生成发布 PR 的取舍

它解决的问题：把版本发布变成一次 PR 合并

很多项目在合并功能后，需要手动更新 CHANGELOG.md、修改 package.json 里的版本号，再打 tag 创建 GitHub Release。这个过程重复且容易出错。release-please 把这件事压缩成一个动作：它维护一个发布 PR，当你准备好时，合并这个 PR 即可。合并后它会自动更新 changelog 和相关语言文件，打上版本 tag，并创建 GitHub Release。它面向的是使用 GitHub 托管代码、并且提交信息遵循 Conventional Commits 规范的团队。它不处理发布到 npm、PyPI 等包管理器的动作，这一点文档里写得很明确。所以它只负责版本与发布说明的生成，不负责真正的分发。

核心机制：解析 git 历史中的 Conventional Commits

release-please 的工作方式不是监听 webhook 事件，而是每次运行时解析 git 历史，查找符合 Conventional Commits 规范的提交。它根据提交前缀决定版本号的变化：fix 对应 patch，feat 对应 minor，带感叹号的破坏性变更对应 major。它把这些提交整理成 changelog 条目，然后生成一个发布 PR。这个 PR 会持续更新，随着新合并的提交而刷新。当你合并这个 PR 后，它才真正打 tag 并创建 Release。这意味着发布节奏由你控制，不是每次合并都触发发布。文档强调，它不会持续发布默认分支上的所有内容，而是维护一个待发布的 PR。

运行方式：从 CLI 到 GitHub Action

release-please 以 npm 包形式发布，也提供了 GitHub Action。命令行方式可以手动触发，例如在 CI 中运行 npx release-please release-pr --token=... 来生成或更新发布 PR。配置通常放在 .release-please-manifest.json 中，指定各包的当前版本。GitHub Action 的用法是在 workflow 中引用 googleapis/release-please-action，并设置 token 和 release-type 等参数。常见配置项包括 release-type（如 node、python、java）、package-name、bump-minor-pre-major 等。具体命令和配置键在 README 中有示例，但完整的配置选项需要查看文档。如果你只是想要快速体验，最直接的方式是使用 GitHub Action，因为它会自动处理 token 和事件触发。

一个提交包含多个变更：footer 机制

实际开发中，一个 PR 可能包含多个独立的功能或修复。release-please 允许你在一个提交的 footer 中列出多个变更。文档给出了例子：在提交正文底部追加 fix(utils): unicode no longer throws exception 和 feat(utils): update encode to support unicode，每个条目可以带自己的 BREAKING-CHANGE 标记。这样一次提交就能生成多个 changelog 条目。但有一个关键限制：这些附加消息必须位于提交的底部，否则不会被识别。这个机制在 squash-merge 下尤其有用，因为你可以在合并前的 PR 描述里写好这些 footer，合并后 commit message 就包含了它们。

强制 squash-merge：为什么不是可选项

README 强烈建议使用 squash-merge，并给出了具体理由：线性历史便于 git bisect、避免 PR 内部的中间提交污染主分支。更重要的是，release-please 的某些功能依赖 squash-merge。比如 BEGIN_COMMIT_OVERRIDE 机制，它允许你通过编辑已合并 PR 的描述来修正提交消息。文档警告说，这个功能在普通 merge 下无法工作，因为 release-please 不知道应该将 override 应用到哪个提交。这意味着如果你使用 merge commit，你将失去修正发布说明的能力。这是 release-please 的一个硬性约束，团队在采用前必须确认自己的合并策略。如果你的项目必须保留 merge commit 以记录 PR 合并历史，release-please 可能不是合适的选择。

常见失败模式：为什么没有生成发布 PR

文档专门列出了排查步骤。第一步是确认是否有可发布单元：只有 feat、fix 和 deps 前缀的提交才会触发发布 PR，chore 和 build 不会。不同语言有不同配置，比如 Java 和 Python 中 docs 也算可发布单元。第二步是检查旧的发布 PR 是否带有 autorelease: pending 或 autorelease: triggered 标签。由于 GitHub API 故障，标签可能没被正确移除，导致 release-please 误以为还有未完成的发布，从而不创建新 PR。这时需要手动移除标签并重新运行。这说明 release-please 的可靠性部分依赖于 GitHub API 的状态，以及维护者对标签的清理。如果你遇到没有发布 PR 的情况，先检查这两点，而不是直接提 issue。

与替代方案的对比：semantic-release 的差异

一个常见的替代方案是 semantic-release。两者都基于 Conventional Commits，但工作方式不同。semantic-release 在每次推送时自动分析提交并立即发布新版本，不需要人工合并发布 PR。release-please 则要求你手动合并发布 PR 才触发 tag 和 Release。这意味着 release-please 给了你一个人工控制点，你可以决定何时发布，而 semantic-release 是自动化程度更高的持续发布。如果你希望完全自动化，semantic-release 可能更合适；如果你需要人工审核发布内容，release-please 的模式更可控。另一个区别是 semantic-release 默认会直接发布到 npm，而 release-please 不处理发布，你需要自己接入发布脚本。

维护与升级成本：版本迭代频繁

release-please 的版本更新相当活跃，从 v17.11.0 到 v17.11.2 只隔了不到一个月。这意味着你可能会频繁看到新版本，但通常 patch 版本是 bug 修复，升级成本较低。作为 GitHub Action 使用时，你可以固定版本或使用 @v17 标签来减少意外变更。由于它是 Apache-2.0 许可，你可以自由使用和修改，但如果你 fork 并维护自己的版本，需要跟上上游的变更。长期来看，最大的维护成本在于确保团队持续遵守 Conventional Commits 规范，以及定期清理 autorelease 标签。如果提交规范变得混乱，release-please 生成的 changelog 就会失真，这时你需要人工干预。

编辑结论

release-please 适合那些已经或愿意采用 Conventional Commits 规范、使用 GitHub 且能接受 squash-merge 工作流的团队。它能显著减少手动更新 changelog 和版本号的重复劳动。不适合以下情况：你无法统一提交规范，或者需要自动化发布到包管理器，因为 release-please 明确不处理发布。在采用前，先验证你的提交历史是否符合规范，特别是检查是否已有带 autorelease: pending 标签的旧 PR 阻碍新 PR 生成。如果你需要更灵活的版本策略或非 GitHub 平台，考虑其他工具。最终，release-please 的价值取决于你能否严格执行其提交约定，否则它会频繁产生错误或忽略变更。

官方来源

1. Official documentation
2. Official README
3. Project repository
4. Release notes