Python包语义化版本管理需依赖动态机制（如setuptools-scm或versioneer）联动Git标签与代码，禁用静态version字段；必须用python-semver进行版本比较，确保CI构建、发布和依赖校验全链路一致。
Python包的版本语义化管理不是靠人肉改version字段就能落地的，核心在于让版本号自动反映代码变更意图，并能被工具链一致读取、比较、发布。手动更新setup.py或__init__.py里的__version__，短期可行，长期必然导致版本号失真、发布漏标、CI判断失效。
pyproject.toml 中 version 字段必须与 Git 标签/提交历史联动
只在pyproject.toml里写死version = "1.2.3"，等于放弃语义化——它无法表达“这是开发中的预发布版”或“基于 v1.2.2 的第5次提交”。真实项目应使用动态版本生成机制：
-
versioneer：通过versioneer.py脚本注入Git元数据，python setup.py version输出类似1.2.3+5.gabc1234，__version__由_version.py自动生成 -
setuptools-scm：更现代的选择，在pyproject.toml中配置：[tool.setuptools_scm] write_to = "src/mypackage/_version.py"
，它直接从最近的v1.2.3标签推导当前开发版 - 不推荐仅靠
bump2version或手写脚本更新静态字符串——它不感知 Git 状态，CI 无法区分正式发布和本地构建
python-semantic-release 要求 commit message 严格匹配约定式提交
这个工具不是“自动发版”，而是“按提交前缀决策发什么版”。它不看代码 diff，只解析 Git 提交信息。一旦配置启用，以下行为会直接触发错误或跳过发布：
- 提交信息不含
feat:、fix:、chore:等前缀 → 被忽略，不计入版本计算 - 含
BREAKING CHANGE:（冒号后换行或空格）→ 强制 bump 主版本号，哪怕只是文档修改 - 分支策略配置错误：比如
branch = "main"但实际用master→ 检测不到新提交，semantic-release静默退出 - 未配置
version_source = "commit"（默认是setup.py）→ 它仍会尝试读setup.py，和动态版本机制冲突
发布前必须验证 wheel 包中 __version__ 是否真实反映当前状态
构建python -m build后，不要只信dist/目录下的文件名。解压生成的.whl，检查内部my_package/__init__.py或my_package/_version.py内容是否包含预期值。常见脱节场景：
立即学习“Python免费学习笔记（深入）”；
- 用
setuptools-scm但没在pyproject.toml中声明[build-system]依赖 → 构建时降级为静态version，wheel 里版本号永远是0.0.0 - CI 环境未安装 Git 或工作区为 shallow clone（
--depth=1）→setuptools-scm无法获取 tag，fallback 到0.0.0 - 本地
git tag v1.2.3后未git push --tags→ CI 拉不到 tag，语义化版本计算失败
python-semver 是运行时校验版本关系的唯一可靠工具
别用字符串比较或正则提取数字来判断"1.10.0" > "1.9.0"——这在 Python 里会错。所有涉及版本比较、范围匹配、兼容性检查的逻辑，必须用python-semver：
from semver import parse, compare, match
v1 = parse("1.10.0")
v2 = parse("1.9.0")
compare(v1, v2) # 返回 1，正确
match("2.1.0", ">=2.0.0 <3.0.0") # True-
semantic_version库已多年未维护，semver是当前事实标准 - PyPI 上传前校验依赖版本范围（如
requests>=2.25.0,<3.0.0）可调用semver.Version.is_compatible() - CI 中做“是否需升级 minor 版本”判断时，用
max_ver([v_old, v_new]) == v_new比字符串操作安全得多
语义化版本真正生效的临界点，是你不再需要解释“为什么这次发 1.2.0 而不是 1.1.1”——所有参与者都信任工具链从提交到 wheel 的全链路一致性。一旦某个环节（比如 CI 构建环境、本地 Git 配置、或 wheel 元数据生成方式）脱离这套闭环，版本号就退化成无意义的数字序列。
