go.mod中require必须写精确语义化版本（如v1.9.1），禁用分支名、commit hash等非法标识；伪版本（v0.0.0-...）虽可复现但应避免；go get指定版本后须运行go mod tidy补全依赖与校验和，go.sum必须提交且不可忽略。
go.mod 文件里 require 的版本号到底怎么写
Go Modules 不靠模糊的“最新版”或“主干”概念，它强制要求每个 require 行必须带明确的语义化版本号（如 v1.9.1），否则 go mod tidy 会报错或自动补全为 latest tag。
常见错误现象：手动编辑 go.mod 时写成 github.com/gin-gonic/gin v1 或 github.com/gin-gonic/gin master —— 这些都不是合法版本标识，Go 工具链会拒绝解析。
-
vX.Y.Z是标准格式，比如v1.9.1；预发布用v1.9.1-beta.2 - 不支持通配符（
v1.*）、分支名（main）、commit hash（e3f4eb5）直接写进require—— 它们只能用于go get命令临时拉取，最终落地仍会被转成对应 tag - 如果依赖没有打 tag，Go 会 fallback 到 pseudo-version，形如
v0.0.0-20240315123456-e3f4eb5，这是可提交、可复现的，但语义弱，应尽量避免长期使用
go get @vX.Y.Z 和 go mod tidy 的协作关系
go get 是“主动变更依赖”的入口，go mod tidy 是“被动收敛依赖状态”的守门人。二者不是替代关系，而是分阶段配合。
典型误操作：只运行 go get github.com/sirupsen/logrus@v1.9.0 就以为升级完成 —— 实际上 go.mod 可能没更新间接依赖，go.sum 可能缺失校验项，CI 构建可能失败。
立即学习“go语言免费学习笔记（深入）”；
-
go get foo/bar@v1.9.0：修改go.mod中该依赖的版本，并触发下载；但不会清理未引用的依赖，也不会补全间接依赖的go.sum条目 -
go mod tidy：扫描全部import，删掉未使用的require，补全缺失的间接依赖，同步更新go.sum—— 必须在go get后手动执行 - 如果想降级某个间接依赖（比如某库引入了有问题的
golang.org/x/net），不能只改它的版本，得先go get golang.org/x/net@v0.17.0，再go mod tidy才生效
replace 和 exclude 不是“快捷修复”，而是显式风险标记
replace 和 exclude 都会绕过 Go 的默认依赖解析逻辑，它们出现在 go.mod 里，就等于告诉所有人：“这里我人工干预了，后果自负”。
容易踩的坑：用 replace 指向本地路径（如 ./my-fork）后提交代码，别人 go build 直接失败 —— 因为路径不存在；或者用 exclude 屏蔽某个间接依赖，结果 runtime panic，因为某库内部实际调用了被排除的函数。
-
replace github.com/old/lib => github.com/new/lib v1.2.0：仅影响构建时解析，不影响go list -m all输出，且目标模块仍需存在有效 tag -
replace github.com/old/lib => ./local-fix：路径必须是相对当前go.mod的有效目录，且该目录下必须有合法go.mod -
exclude github.com/bad/dep v0.3.1：仅阻止该版本被选中，不阻止其他版本；若多个依赖需要不同版本，exclude可能引发 MVS 算法无解，导致go mod tidy失败
go.sum 不是锁文件，但必须和 go.mod 一起提交
go.sum 记录的是所有直接+间接依赖的 checksum，不是“版本锁定”，而是“内容防篡改快照”。它不决定用哪个版本，只校验下载下来的包是否和开发者当时看到的一致。
最常被忽略的点：CI 流程里跳过 go.sum 校验，或开发机上 go mod download 后自动生成并提交了新 go.sum —— 这会导致团队成员拉代码后 go build 报 checksum mismatch。
-
go.sum必须进 Git，且每次go mod tidy后都要重新提交 - 禁止在 CI 中设
GOSUMDB=off或删go.sum再go mod download—— 这等于关掉供应链安全阀 - 如果遇到
checksum mismatch，优先查是不是有人手动改过go.mod但没跑tidy，而不是直接删go.sum
