setuptools_scm能从Git标签生成版本号，但要求项目根目录有.git且已打符合语义化规范的tag（如v1.2.3），否则fallback为dev格式；需在pyproject.toml中正确配置build-system和project.dynamic=["version"]，并确保CI获取完整Git历史。
直接用 setuptools_scm 就能从 Git 标签生成版本号，但前提是你的项目根目录有 .git，且已打过符合语义化规范的 tag（如 v1.2.3）。否则它会 fallback 到“未发布”格式（如 0.1.0.dev1+gabc1234），不是你想要的稳定版号。
确保 Git 仓库状态满足 setuptools_scm 要求
setuptools_scm 不读 setup.py 或 pyproject.toml 以外的任何元数据，它只依赖 Git 历史。常见失败原因不是配置错，而是仓库本身不达标：
- 项目目录必须是 Git 工作区根目录（即运行
git rev-parse --show-toplevel应返回当前路径） - 最近一次 commit 必须有 tag，且 tag 名要匹配默认正则
^v?(\d+\.\d+\.\d+)$（比如v1.2.3或1.2.3都行，release-1.2.3就不行） - 如果没 tag，它会按距离最近 tag 的提交数 + 当前 commit hash 构造 dev 版本，这不是 bug，是设计行为
在 pyproject.toml 中启用 setuptools_scm
现代 Python 项目应使用 pyproject.toml，而不是旧式 setup.py。关键配置只有两处，别多写：
[build-system]
requires = ["setuptools>=45", "setuptools_scm[toml]>=6.2"]
build-backend = "setuptools.build_meta"
<p>[project]
name = "mylib"</p><h1>不要写 version 字段！交给 setuptools_scm 动态生成</h1><p>dynamic = ["version"]</p><p><span>立即学习</span>“<a href="https://pan.quark.cn/s/00968c3c2c15" style="text-decoration: underline !important; color: blue; font-weight: bolder;" rel="nofollow" target="_blank">Python免费学习笔记（深入）</a>”；</p><div class="aritcle_card flexRow">
<div class="artcardd flexRow">
<a class="aritcle_card_img" href="/xiazai/skill6458" title="GitHub Iteration Workflow"><img
src="https://img.php.cn/upload/skill/000/000/081/179094614154731.jpg" alt="GitHub Iteration Workflow" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a>
<div class="aritcle_card_info flexColumn">
<a href="/xiazai/skill6458" title="GitHub Iteration Workflow">GitHub Iteration Workflow</a>
<p>GitHub Issue 全流程自动化：自动拉取、修复 Issue，创建 PR，监控 CI/CD，合并部署。</p>
</div>
<a href="/xiazai/skill6458" title="GitHub Iteration Workflow" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span> </a>
</div>
</div><p>[project.optional-dependencies]
dev = ["setuptools_scm"]</p><p>[tool.setuptools_scm]</p><h1>可选：放宽 tag 匹配规则（例如支持 'v1.2.3-beta.1'）</h1><h1>version_scheme = "guess-next-dev"</h1><h1>local_scheme = "node-and-date"注意：dynamic = ["version"] 是必需的，否则 setuptools 会忽略 setuptools_scm 的注入；requires 里必须显式包含 setuptools_scm[toml]，否则 toml 解析器可能缺失。
验证版本号是否真被正确读取
别靠 pip install -e . 后 import 看 __version__ —— 这个值可能来自源码里硬编码的 fallback，而非 Git。真正可靠的验证方式是：
- 运行
python -m setuptools_scm：它会直接输出当前解析出的版本字符串，且附带调试信息（如 “tag ‘v1.2.3’ found” 或 “no tag found”） - 构建 sdist/wheel 后解压，检查生成的
PKG-INFO或mylib-*.dist-info/METADATA里的Version:字段 - 在干净虚拟环境中
pip install ./dist/mylib-*.tar.gz，再import mylib; print(mylib.__version__)
如果 python -m setuptools_scm 输出的是 0.0.0，说明它根本没找到 Git 信息——大概率是当前路径不在 Git 仓库内，或 .git 被误删/忽略。
最常被忽略的一点：CI 环境中 clone 的仓库默认是 shallow（--depth=1），没有完整历史和 tag。必须显式加 git fetch --tags --prune 或设置 fetch-depth: 0（GitHub Actions）才能让 setuptools_scm 正常工作。
