如何用 poetry version 按 bump 规则升级项目版本？

在维护一个用 Poetry 管理的包时，每次发布前都需要把 pyproject.toml 中记录的版本号按 semver 规则提升：修一个 bug 升 patch、加新功能升 minor、有破坏性变更升 major。Poetry 自带的 poetry version 命令可以显示项目当前版本，也可以在给定一个 bump 规则（如 patch、minor、major）后自动计算新版本并写回 pyproject.toml，不需要手动编辑文件。前提是项目已初始化且 pyproject.toml 中定义了 version 字段（[project] 段或 [tool.poetry] 段均可，包模式下该字段是必填的，见 pyproject.toml 说明）。

查看当前版本

在项目根目录执行：

poetry version

输出格式为“项目名 版本号”，例如文档测试中 simple-project 当前版本为 1.2.3 时输出：

simple-project 1.2.3

如果只需要版本号本身（方便在脚本中使用），加 --short：

poetry version --short
# 输出：1.2.3

可用的 bump 规则

poetry version 的参数是一个合法的 PEP 440 版本字符串，或以下 7 个 bump 规则之一：patch、minor、major、prepatch、preminor、premajor、prerelease。

docs/cli.md 给出的各规则效果示例如下（before/after 均为文档示例，用于说明规则行为）：

rule	before	after
major	1.3.0	2.0.0
minor	2.1.4	2.2.0
patch	4.1.1	4.1.2
premajor	1.0.2	2.0.0a0
preminor	1.0.2	1.1.0a0
prepatch	1.0.2	1.0.3a0
prerelease	1.0.2	1.0.3a0
prerelease	1.0.3a0	1.0.3a1
prerelease	1.0.3b0	1.0.3b1

major/minor/patch 用于正式版本，pre* 系列用于在下一个正式版本前插入预发布版本。如果你的项目采用语义化版本，版本选择依据可参考 Libraries 文档的 Versioning 一节。

先 --dry-run 预览，再正式执行

poetry version 会直接修改 pyproject.toml，不确定结果时可以先用 --dry-run 选项：它会执行版本计算并打印结果，但不更新 pyproject.toml 文件。

# 预览：将 1.2.3 按 major 提升到 2.0.0，不写入文件
poetry version --dry-run major

此时终端会看到类似这样的输出（文档测试中的示例结果）：

Bumping version from 1.2.3 to 2.0.0

确认无误后去掉 --dry-run 正式执行：

poetry version major

也可以用 --short 让 bump 后只输出新版本号：

poetry version --short patch
# 输出：1.2.4

验证版本号已写回

执行 bump 后再查询一次版本，确认 pyproject.toml 已被更新：

poetry version --short

输出应为 bump 后的新版本号。也可以直接查看 pyproject.toml 中 version 字段。

另外，直接把目标版本作为参数传入也可以跳过规则计算，参数可以是任意合法的 PEP 440 字符串：

poetry version 2.0.0
# 输出：Bumping version from 1.2.3 to 2.0.0

预发布版本与 --next-phase

prerelease 规则作用于预发布阶段号：对正式版本会先产生下一个 patch 的 a0 预发布（如 1.0.2 → 1.0.3a0）；对已有预发布版本则递增阶段内的序号（1.0.3a0 → 1.0.3a1）。

如果需要跨阶段推进（alpha → beta → rc → 正式版），加上 --next-phase 选项。文档给出的效果示例：

rule	before	after
prerelease --next-phase	1.0.3a0	1.0.3b0
prerelease --next-phase	1.0.3b0	1.0.3rc0
prerelease --next-phase	1.0.3rc0	1.0.3

poetry version prerelease --next-phase

注意事项

• 当前项目版本必须能被解析为合法的 semver/PEP 440 字符串，否则版本计算会失败；Libraries 文档 也强调 Poetry 要求所有项目版本符合 PEP 440（例如 1.0.0-hotfix.1 不合法，可改用 1.0.0-post1）。
• --dry-run 只做预览不写文件；不加该选项时，poetry version <规则> 会立即把新版本写回 pyproject.toml，执行前可用 git 状态确认改动范围。
• 命令在哪个项目下执行，就修改哪个项目的 pyproject.toml；需要操作其他目录的项目时，可用全局选项 --directory 指定工作目录（见 Commands 文档）。