go.mod 版本变 pseudo-version 是因 Git 标签丢失或未同步：远程缺失轻量 tag（如 v1.2.3）时 Go 退而使用 commit hash；需执行 git push origin --tags 并确保 CI 使用 git fetch --tags --depth=0。
主干合并后 go.mod 中的版本号突然变成 pseudo-version？
这是最典型的标签错乱现象：你刚合入一个 PR，go.mod 里某个依赖从 v1.2.3 变成了 v1.2.3-0.20251201102233-abcdef123456。根本原因不是代码冲突，而是 Git 标签丢失或未同步——Go 在找不到对应 tag 时，会退而使用 commit hash 生成 pseudo-version。
检查方式很简单：git ls-remote --tags origin | grep 'module-name'。如果目标模块在远程仓库没有 v1.2.3 这个轻量 tag（只有 annotated tag 或压根没推），go mod tidy 就会“降级”处理。
- 确保所有依赖模块的发布 tag 都已
git push origin --tags推送，不只是git push - 若依赖是私有模块，确认 CI 构建时使用的 Git 深度足够（
git clone --depth=0才能拿到全部 tag） - 别依赖本地未推送的 tag 测试：本地
go get ./mymodule@v1.2.3成功 ≠ 远程 CI 能解析成功
合并 PR 后 go.sum 校验失败：checksum mismatch
现象是 go build 或 go mod verify 报错：github.com/example/lib v1.2.3: checksum mismatch。这通常是因为主干合并时，某人手动改了 go.mod 却没跑 go mod tidy，导致 go.sum 里存的是旧 commit 的哈希，而 go.mod 指向了新 commit。
- 立刻运行
go mod tidy -v（加-v看实际下载的 commit），观察输出中是否出现 “downloading github.com/example/lib v1.2.3” 后又提示 “verifying github.com/example/lib@v1.2.3” 失败 - 若确认远程 tag 内容未变，直接删掉
go.sum中对应行，再执行go mod tidy重建 - CI 流程中必须加入
go mod verify，且失败即退出；不能只靠go build—— 它默认跳过校验
多个团队共用同一模块，主干合并后版本回退到旧 tag？
比如 A 团队刚发 v2.1.0，B 团队的 PR 合入后，go.mod 却回退成 v2.0.5。这不是 Git 冲突，而是 MVS（最小版本选择）在起作用：B 团队的某个依赖仍硬编码要求 v2.0.5，而 go mod tidy 认为它“足够新”，就放弃了 v2.1.0。
立即学习“go语言免费学习笔记（深入）”；
- 用
go mod graph | grep 'example/lib'查谁在拉v2.0.5 - 再用
go mod why -m github.com/example/lib看完整引入链，定位是哪个间接依赖卡住了版本 - 不要直接
replace；优先让那个间接依赖升级——或者显式执行go get github.com/example/lib@v2.1.0，强制提升主模块的 require 行 - 团队间应约定：major 版本升级必须同步更新所有下游的
go.mod，并在 PR 描述中标注“requires v2.1.0”
CI 构建因标签错乱失败，但本地一切正常？
本地有缓存、有完整 Git 历史、甚至有未推送的 tag，而 CI 是干净 clone，只 fetch 默认 depth 的 commit。这就是为什么“本地能过，CI 报 no matching versions”。
- CI 脚本开头必须加
git fetch --tags --depth=0，确保所有 tag 可见 - 禁止在
go.mod中使用本地路径replace（如replace example.com/lib => ./local-fork）——CI 根本没有这个目录 - 如果必须用 fork，用
replace example.com/lib => github.com/yourname/lib v2.1.0-fork.1，并确保该 tag 已推送到你的 fork 仓库 - GO111MODULE=on 和 GOPROXY=https://proxy.golang.org,direct 必须显式设置，避免 fallback 到 GOPATH 模式
go list -m -f '{{.Path}} {{.Version}} {{.Indirect}}' all | grep your-module 快速扫一眼当前解析出的版本，比等 CI 失败后再排查快得多。 
