Git分支场景下Pip Whl包命名规范与版本管理方案咨询

核心原则：不要试图突破PEP 440版本规范硬塞分支信息，把「分支溯源」和「便捷安装」两个需求拆分实现，不要绑定在版本号单个字段上解决。

1. 版本号合规配置：解决分支溯源问题 #

直接复用setuptools_scm的原生能力即可，不需要自定义版本规则：

• 调整setuptools_scm的local_scheme配置，自定义本地版本段生成逻辑：把当前Git分支名做字符合规替换（将/、_等PEP 440本地段不支持的特殊字符统一替换为.，例如feature/pay-refactor转为feature.pay.refactor），拼接到默认生成的本地版本段末尾，最终生成的版本格式类似0.1.dev41+gabcdef12.feature.pay.refactor。
• 这种格式完全符合PEP 440规范，上传开发PyPI后，包列表里可以直接看到每个版本对应的分支和提交哈希，不需要额外查CI记录溯源。同时pip默认不会优先选择带本地版本段的包，也能避免开发分支包被意外安装到生产环境。

2. 便捷安装方案：解决分支最新包拉取成本高的问题 #

PEP 440本身不支持通过本地版本段做模糊匹配安装，不要死磕pip install package==分支名的逻辑，业内通用两种无兼容问题的实现：

方案A：分支专属包名后缀（中小团队首选，零额外运维成本） #

• CI构建非主分支包时，自动给包名追加合规化的分支名后缀，例如主分支发布的包名是your-project，feature/pay-refactor分支构建的包统一命名为your-project-feature-pay-refactor，版本号正常按规则生成即可，不需要额外携带分支信息。
• 在分支包的项目配置中，将原项目名声明为对应当前版本的依赖，测试人员需要测某分支最新代码时，直接执行pip install your-project-feature-pay-refactor，pip会自动拉取该分支最新上传的构建包，完全不需要提前查版本号，也不需要额外沟通。
• 可以在开发PyPI上配置自动清理规则，对应Git分支删除后，自动清理该后缀下的所有历史包，避免索引冗余。

方案B：动态索引路由（中大型团队/有自研DevOps能力首选） #

• 在开发PyPI上层加一层轻量的PEP 503简单索引代理，当用户请求特定分支的索引路径时，自动过滤出对应分支最新的构建包列表返回。测试人员安装指定分支包时直接执行：

pip install your-project --index-url https://dev-pypi.example.com/simple/your-project/feature/pay-refactor/

• 这种方案完全不需要修改包名、不需要魔改版号规则，对开发流程无侵入，团队分支数量多的时候长期维护成本最低。

不推荐方案的核心问题 #

• 把分支名直接塞入公版版本段的做法违反PEP 440规范，会导致pip、poetry、pdm等所有依赖解析工具出现版本排序错误，甚至可能把旧分支的过期包判定为最新版本，引发依赖事故。
• 用alpha/beta/rc预发布标签标记分支版本的做法不支持并行开发：预发布版本号是全局有序的，两个并行分支同时提交会生成重复的版本号（比如都生成0.1a42），会被PyPI直接拒绝上传，完全适配不了多分支并行开发的场景。

内容的提问来源于stack exchange，提问作者John Sallay