Go Modules中使用main分支会导致checksum mismatch，因其被解析为v0.0.0-时间戳伪版本，force push重写历史后commit hash变更使go.sum校验失败；应避免require main，改用稳定tag或replace指向具体伪版本/本地路径。
go get main 分支变动导致依赖解析失败
主分支（main）不是语义化版本，Go Module 会把它当作 v0.0.0- 时间戳伪版本处理；一旦上游重写 main 历史（如 force push），本地缓存或 go.sum 中的校验和就失效，触发 verifying github.com/xxx@v0.0.0-20240101000000-abcdef123456: checksum mismatch 错误。
常见现象包括：
-
go build或go mod download卡住并报 checksum mismatch -
go list -m all显示版本号正常，但go mod verify失败 - CI 构建成功、本地构建失败，或反之
根本原因是 Go 不校验 main 分支内容一致性，只认 commit hash 和签名——而重写历史后 hash 变了，旧 go.sum 记录就作废。
实操建议：
- 永远不要在生产项目中
requiremain分支：运行go get github.com/xxx@main后立即执行go mod edit -droprequire github.com/xxx回退，改用稳定 tag - 若必须用
main（如调试未发版功能），用replace指向具体 commit：replace github.com/xxx => github.com/xxx v0.0.0-20240101000000-abcdef123456，再go mod tidy - 遇到 checksum mismatch，先删
go.sum中对应行（或整文件），再go mod download重新生成；不要盲目go clean -modcache，它不清理go.sum校验项
replace 指向 main 分支时的实际生效条件
replace 写成 replace github.com/xxx => github.com/xxx main 是无效的——Go 不接受分支名作为版本标识符，会忽略该行，仍走原始解析逻辑。
真正能生效的写法只有两种：
- 指向带时间戳的伪版本：
replace github.com/xxx => github.com/xxx v0.0.0-20240101000000-abcdef123456（需确保该 commit 真实存在且未被 force push 覆盖） - 指向本地路径：
replace github.com/xxx => ../xxx（适合调试，但 CI 中必须移除或替换为真实 tag）
验证是否生效：
- 运行
go list -m github.com/xxx，输出应含你指定的伪版本号或(devel)标识 - 检查
go mod graph | grep github.com/xxx，确认依赖图中无其他路径引入同模块不同版本 - 若仍有冲突，说明其他间接依赖也拉了
main，需对它们也做replace或升级其版本
如何从 main 分支安全过渡到正式版本
团队协作中常有人先推 main 再打 tag，导致下游模块短暂“失联”。这不是 bug，是 Go 对未发布代码的默认保守策略。
正确过渡步骤：
- 上游项目发版前，先在
main上跑通全部测试，再执行git tag v1.2.3 && git push origin v1.2.3 - 下游项目收到通知后，执行
go get github.com/upstream/repo@v1.2.3，而非@main - 若下游已用
replace指向main的伪版本，删掉该行，再go mod tidy—— 它会自动降级为require github.com/upstream/repo v1.2.3 - 禁止在
go.mod中保留形如// temporary: using main until v1.2.3 released的注释，这类“临时”往往变成永久
容易被忽略的一点：Go 1.21+ 默认启用 GOSUMDB=sum.golang.org，对伪版本校验更严格。若上游私有仓库未配置 GONOSUMDB，即使打了 tag，也可能因 sumdb 无法验证而失败。
