Go项目版本控制由go.mod版本号与go.sum哈希共同决定，Git tag不更新go.mod则无效；有效写法仅三种：v1.2.3（需对应带v前缀tag）、伪版本（自动生成）、latest/master（不推荐）；go.sum是防篡改校验依据，必须提交；私有库需配置GOPRIVATE；replace/exclude仅为临时手段。
Go 项目里所谓“版本控制”，不是 Git tag 管的，而是 go.mod 里写的版本号 + go.sum 里的哈希值共同决定的。你改了 Git tag 但没改 go.mod，go build 依然用旧版本。
go.mod 中的版本号到底怎么写才有效
Go 不认 Git 分支名或裸 commit hash，只认模块系统能解析的版本格式。常见写法有三种，行为完全不同：
-
v1.2.3：语义化版本，必须对应 Git tagv1.2.3（带v前缀），否则go get会报unknown revision -
v0.0.0-20240501123456-abc123def456：伪版本，用于未打 tag 的 commit，由时间戳 + commit hash 构成，Go 自动生成，手动写容易出错 -
latest或master：不推荐。前者触发最小版本选择（MVS）找兼容最高版，后者绕过 SemVer 直接拉 HEAD，极易引入破坏性变更
真正安全的做法是：先在代码里 import 并调用新 API，再运行 go mod tidy —— 它只升到满足当前 import 需求的最小版本，不会盲目跨主版本。
go.sum 不是可选文件，它是构建校验的唯一依据
go.sum 记录每个模块版本的 SHA256 校验和，每次 go build 或 go test 都会核对下载内容是否匹配。它不是“锁文件”，而是防篡改快照。
立即学习“go语言免费学习笔记（深入）”；
- Git 忽略
go.sum→ 不同机器go build可能拉到不同内容，触发checksum mismatch错误 - CI 中执行
go mod download后提交生成的go.sum→ 开发者本地go mod tidy会重写它，导致校验失败 - 手动编辑
go.sum→ 下次go mod tidy会覆盖，且破坏完整性验证逻辑
正确做法：开发者运行 go mod tidy 后，把生成的 go.mod 和 go.sum 一起提交；CI 流程中禁用 GOSUMDB=off，也不删 go.sum。
私有库依赖必须配 GOPRIVATE，否则 go get 会失败
Go 默认把所有模块请求转发给 proxy.golang.org，遇到私有域名（如 git.internal.company.com）会直接 403 或 timeout，根本不会走 Git 协议。
- 设置
GOPRIVATE=git.internal.company.com/*（支持通配符），告诉 Go “这些域名不走 proxy” - 若用 SSH 地址（
git@git.internal.company.com:user/repo.git），需在~/.gitconfig加：[url "git@git.internal.company.com:"] insteadOf = https://git.internal.company.com/ -
go.mod中的 module path 必须与仓库根路径完全一致，比如git.internal.company.com/user/repo，否则go mod download找不到对应 commit
漏配 GOPRIVATE 是私有库场景下最常踩的坑，错误现象通常是 module git.internal.company.com/user/repo: reading git.internal.company.com/user/repo/go.mod at revision xxx: 403 Forbidden。
replace 和 exclude 都是临时手段，别长期留在 go.mod 里
replace 和 exclude 解决的是特定场景问题，不是版本管理常规路径。长期保留会导致协作和 CI 行为不可预测。
-
replace github.com/some/lib => ./local-fix：仅限本地调试，上线前必须删掉，否则别人go build会拉不到这个路径 -
exclude github.com/bad/lib v1.2.0：只应在间接依赖存在严重漏洞且上游未修复时临时使用，它会让 MVS 算法跳过该版本，但可能引发其他依赖解析失败 - 二者都会让
go list -m all输出失真，影响依赖分析和安全扫描
真正要落地的版本策略，始终落在 go.mod 的 require 行 + 对应的 Git tag 上。其他都是过渡态，不该进主干分支。
