如何用 bumpversion 实现可选开发版本后缀的策略与实践

在 Python 项目与各类库发布过程中，我们经常需要在日常构建中标记出“这是开发中的版本”，例如 1.2.0.dev3，而在正式发布时又必须得到干净的 1.2.0。bumpversion 作为常用的版本变更工具，其原生设计偏向简单的数字段递增，并不直接内置“可选后缀”概念。要让它支持按需添加或去除开发后缀，需要理解它的 part 机制与配置覆盖方式。

理解 bumpversion 的版本组成模型

bumpversion 将版本号拆分为多个 part，例如 major、minor、patch，每个 part 有独立的正则表达式与递增逻辑。默认配置下，版本字符串由这些 part 按顺序拼接，不支持动态插入可选文本。如果直接把 dev 写死在 format 中，那么每一次 bump 都会携带 dev，显然不符合正式发版需求。

要实现“可选”效果，核心思路是把后缀也抽象成一个 part，例如叫做 release 或 devtag，并让其值可以为空。通过为不同场景准备不同的配置文件或命令行参数，控制该 part 是否参与最终字符串渲染。这样既能用同一个工具链，又不会污染正式版本。

基础配置结构

下面是一段最小可用的 .bumpversion.cfg，其中定义了 devtag 这个可选 part，并允许它匹配空字符串或 dev加数字：

[bumpversion]
current_version = 1.2.0
commit = True
tag = False
parse = (?P<major>d+).(?P<minor>d+).(?P<patch>d+)(?:.(?P<devtag>devd+))?
serialize = 
	{major}.{minor}.{patch}.{devtag}
	{major}.{minor}.{patch}

[bumpversion:part:devtag]
optional_value = 
values = 
	dev0
	dev1
	dev2
	dev3
	dev4

[bumpversion:file:pyproject.toml]

注意 serialize 中第一行包含 devtag，第二行不含，这允许 bumpversion 在 devtag 为空时退化为纯净版本。parse 里的问号表示 devtag 整体可选，这是实现可选后缀的关键正则语法。

开发构建与正式发版的策略分离

在 CI 的开发流水线中，我们可以显式 bump devtag 部分，命令如下：

bumpversion devtag --no-commit --allow-no-changes

该命令让 devtag 在 dev0 到 dev4 之间循环，若当前已是 dev4 则配合 patch 递增并重置。而在正式发布时，我们使用另一份配置或同一配置但指定 devtag 为空：

bumpversion devtag --no-commit --new-version 1.2.0

这样生成的版本号不再带 dev 后缀。对比“写脚本直接改字符串”的方案，纯 bumpversion 配置的优势在于所有版本规则集中在文件里，审计与回滚更清晰，也不会因忘记调用脚本而发出错误版本。

常见问题与避坑

很多团队初次使用时，把 parse 写成必须包含 dev 的形式，导致正式版无法匹配，bumpversion 直接报错退出。务必确认正则中后缀部分是可选组，且 serialize 提供无后缀模板。另一个误区是在 pyproject.toml 中用动态字段引用，却未同步更新锁文件，造成构建环境与发布环境版本不一致。

如果项目采用 trunk-based 开发，建议将 dev 后缀仅用于预发布轮子（wheel），正式 tag 前用 bumpversion 的 dry_run 校验一次配置，确认输出符合预期再真实写入，能大幅降低误操作率。

完整实践示例

假设我们需要在每次合并到 develop 时自动追加开发后缀，发版时去除，可参考以下 GitHub Actions 片段逻辑（已简化为命令）：

steps:
  - name: Bump dev version
    if: github.ref == 'refs/heads/develop'
    run: |
      bumpversion devtag --no-commit --allow-no-changes
  - name: Release clean version
    if: startsWith(github.ref, 'refs/tags/v')
    run: |
      bumpversion devtag --no-commit --new-version ${GITHUB_REF_NAME#v}

该方式让开发版本自然呈现为 1.3.0.dev1 之类，而 tag 触发时强制覆盖为 1.3.0。结合前文配置，无需额外 Python 脚本即可达成可选后缀目标。

总体来看，bumpversion 实现可选开发版本后缀并不复杂，重点在于正确设计 part 与 serialize 的空值兼容。掌握这一模式后，无论是 Python 包、Node 库还是内部服务版本标记，都能复用同一套思路保持发布规范性。

bumpversion版本管理开发版本后缀修改时间：2026-08-02 10:39:25