GitHub Actions 算错发布版本：checkout 只取了一层历史

本地执行版本计算能找到上一个发布标签，放进 GitHub Actions 后，却把很多未修改的包判为需要发布，或报找不到可用标签。代码文件看上去完整，不代表 Runner 上的 Git 历史也完整。

actions/checkout 4.2.2 默认只抓取触发工作流的一个提交，fetch-depth 为 1。如果发布工具需要沿提交历史寻找标签、比较上次发布，浅克隆就可能改变计算结果。先确认版本工具实际依赖什么，再决定是否增加抓取范围；普通编译任务不必因此全部下载历史。

看清缺的是历史还是标签

在 checkout 后、版本计算之前加入只读检查：

git rev-parse --is-shallow-repository
git rev-parse HEAD
git tag --list
git log -5 --oneline --decorate

第一条返回 true，说明当前仓库是浅仓库。标签列表为空是另一个线索，但有标签也不证明它们与当前提交之间的历史已经完整。用本地项目相同的版本计算命令检查，不要只凭 git tag 有输出就认定问题解决。

还要核对 HEAD 是否对应这次发布准备使用的提交。Pull Request 工作流可能检出合并测试引用；在错误提交上补齐历史，仍会得到不符合发布预期的版本。

如果远程仓库根本没有所需标签、标签位于另一条分支，或发布工具限制了标签格式，增加抓取深度不能修复这些条件。先对照已知的上次发布提交和标签，再看工作流的输入。

需要历史计算时，明确抓取完整历史

以下是合入现有任务的步骤片段，按 checkout 4.2.2 的输入行为编写：

steps:
  - uses: actions/checkout@v4.2.2
    with:
      fetch-depth: 0
      persist-credentials: false
  - name: Inspect release history
    run: |
      git rev-parse --is-shallow-repository
      git rev-parse HEAD
      git tag --list

fetch-depth: 0 抓取所有分支和标签的历史；Git 仓库检出路径保持原工作流设置。示例关闭后续 Git 凭据持久化，适用于只读计算版本的任务。已有任务确实需要后续认证操作时，应单独核对所需权限，不能为了计算版本直接增加写权限。

fetch-tags: true 与 fetch-depth: 0 的用途不同。前者允许浅抓取时也取得标签，不会自动把当前提交到历史标签之间缺失的提交全部补回来。对于依赖祖先关系的发布工具，仅打开标签开关仍可能不够。

设置完整抓取后，不要再追加 git fetch --depth=1 ... 当作通用补丁。新的浅抓取可能重新影响相关引用的历史边界，使后面的版本判断更难解释。额外抓取应有明确的引用和深度需求。

发布前只验算，不急着上传

保存原工作流，先在不执行包发布或镜像推送的验证任务中运行项目已有的版本预览功能。检查浅仓库标记、上次发布标签、待发布包列表以及计算后的版本，确认它们对应同一提交。

历史完整后仍算错，就检查工具配置中的标签前缀、包名映射和发布基线。不要把缓存清空、重新安装依赖当成 Git 历史问题的默认处理。

如需撤回，恢复原 checkout 参数并重新验算；恢复工作流不会撤销已经创建的标签或发布的包。GitHub 网页与本地分支列表不一致时，可另按远程跟踪引用的检查方法核对，那个问题涉及引用是否过期，与这里的历史深度不同。