go.mod中的go版本声明仅影响工具行为，不决定运行时特性；真正起作用的是本地GOROOT的Go版本，构建时若版本低于//go:build约束则直接跳过对应文件。
go.mod 里的 go 版本声明只影响工具链，不决定运行时特性
很多人误以为在 go.mod 里写 go 1.22 就能让代码用上 Go 1.22 的新语法或行为——其实不是。真正起作用的是你本地 GOROOT 指向的 Go 安装版本。比如你 go.mod 写了 go 1.24，但用 go1.21 构建，那所有 //go:build go1.22 或 for range 变量捕获优化（Go 1.22+）都会被跳过。
常见错误现象：
- 本地跑通，CI 失败：CI 使用的 Go 版本低于
go.mod声明，导致构建跳过条件编译文件 - 误判兼容性：以为升级
go行就能启用新特性，结果 runtime 行为没变
实操建议：
- 检查实际构建环境：运行
go version，而非只看go.mod - CI 配置中显式指定 Go 版本（如 GitHub Actions 的
go-version: '1.24'），避免依赖系统默认 - 若需多版本验证，用
gvm或asdf切换本地GOROOT，再跑go build
同一模块路径下 v1 和 v2+ 版本不能共存，除非路径显式分隔
Go 不允许 github.com/user/lib 同时存在 v1.5.0 和 v2.0.0——这不是“冲突”，而是直接报错：invalid version: module contains a go.mod file, so major version must be compatible。唯一合法的多版本共存方式是路径后缀区分，例如 github.com/user/lib/v2 被 Go 视为独立模块。
立即学习“go语言免费学习笔记（深入）”；
典型踩坑场景：
- 第三方库发布 v2 但没加
/v2路径，你的项目 upgrade 后所有 import 必须手动改路径 - 误删
/v2后缀，导致go get拉到 v2 却仍 import 原路径，编译失败 - fork 一个库并打 v2 tag，但没同步更新其内部
go.mod的 module 名，下游无法正确识别
实操建议：
- 升级主版本前，先查原库是否已按规范发布带路径后缀的版本（
go list -m -versions github.com/user/lib） - 手动修改 import 路径后，立刻跑
go mod tidy，它会自动补全对应require github.com/user/lib/v2 v2.x.y - 不要靠
replace“伪装” v2 路径，这会让其他依赖无法感知真实模块身份
go get @tag 不一定生效，关键看 MVS 是否允许降级
go get github.com/sirupsen/logrus@v1.9.3 执行后 go.mod 没变，不是命令失效，而是 Go 的最小版本选择（MVS）策略拒绝降级：如果已有 v2.0.0+incompatible 被某个依赖拉入，MVS 会优先保留更高主版本，除非你显式干预。
常见表现：
- 执行后
go.mod仍是v2.0.0+incompatible，甚至变成v2.1.0 -
go list -m github.com/sirupsen/logrus显示 v2，但代码里 import 的却是github.com/sirupsen/logrus（非/v2），类型不匹配
实操建议：
- 强制锁定用
go mod edit -require=github.com/sirupsen/logrus@v1.9.3+go mod tidy - 确认 tag 存在：访问
https://proxy.golang.org/github.com/sirupsen/logrus/@v/v1.9.3.info，HTTP 200 才可靠 - 更稳妥用 commit hash：
go get github.com/sirupsen/logrus@55046e2，绕过 tag 解析和语义校验
vendor 目录不等于离线安全，缺了 go.sum 就失去校验意义
把 vendor/ 提交到 Git 并不保证构建可重现——如果 go.sum 没一起提交，或者 CI 环境没启用 -mod=vendor，Go 仍会走 GOPROXY 下载，并可能拉到被篡改的包。
容易被忽略的细节：
-
go mod vendor只复制go.mod中声明的依赖，不会更新已存在但版本过时的 vendor 内容 - 私有模块或无签名仓库下，
go.sum是唯一防篡改依据；丢掉它，vendor 就只是个普通文件夹 - CI 中仅检查
vendor/是否存在不够，必须加git status --porcelain go.sum防哈希漂移
实操建议：
- 每次
go mod tidy后重跑go mod vendor，并确保go.mod、go.sum、vendor/三者同时提交 - 构建命令明确写
go build -mod=vendor，别依赖默认行为 - 本地开发可设
GOFLAGS="-mod=vendor"，避免手误触发 proxy 请求
go.sum 和 vendor 的协同关系——这些地方稍一松懈，就会让“本地能跑”变成“上线就崩”。 
