go.mod必须位于模块根目录且路径与import路径一致，//indirect依赖不可删除，go.sum是完整性校验非缓存，v2+模块路径须含/v2后缀，replace/exclude不传递且go.sum哈希不跨模块继承。
go.mod 文件必须存在且位置正确
没有 go.mod，Go 就不认为你是在用模块模式——它会退回到已弃用的 GOPATH 模式，导致 go build、go test 解析 import 路径失败，CI 环境尤其容易出错。
关键约束只有两条：
-
go.mod必须在模块根目录（即你执行go mod init example.com/myapp的地方） - 该路径必须与你期望被别人
import的模块名完全一致（比如别人写import "example.com/myapp/pkg/util"，那go.mod里的module行就必须是module example.com/myapp）
常见错误：在子目录里运行 go mod init，结果生成了 cmd/myserver/go.mod——这会让整个项目变成两个模块，主模块反而没 go.mod，依赖无法统一管理。
require 中 // indirect 行不是“可有可无”的注释
带 // indirect 的 require 行，表示这个包没被你的代码直接 import，而是某个你直接依赖的包内部用到了它。Go 必须锁定它的版本，否则不同机器上 go build 可能拉到不同版本，引发符号缺失或行为不一致。
立即学习“go语言免费学习笔记（深入）”；
典型问题场景：
-
go mod tidy后突然多出几十行// indirect，甚至版本比之前还低 - 本地能跑，CI 报错
undefined: xxx—— 很可能是间接依赖版本不匹配
不要手动删掉它们。想升级某个 // indirect 包？先查谁在用：go mod graph | grep package-name；确认后用 go get package-name@v1.2.3，Go 会把它提到顶层并去掉标记。
go.sum 不是缓存，是构建完整性校验锁
go.sum 记录的是每个依赖模块 zip 包内容的哈希值（SHA256），不是“下载缓存”。只要内容变了，校验就失败，报 checksum mismatch。
触发原因很实际：
- 换机器拉代码，但公司代理缓存了旧版 zip
- 私有模块没配置
GOPRIVATE，Go 误走公共代理，写入了错误哈希 - 上游包被恶意篡改（极少见，但校验机制就是防这个）
别直接删 go.sum 或加 -dirty 参数绕过——这等于主动放弃供应链安全。优先检查网络和 GOPRIVATE 设置；真要重建，用 go mod download -dirty && go mod verify && go mod tidy 三步走。
模块路径里的 /v2 是硬性语法要求，不是命名习惯
从 v2 开始，模块路径必须带主版本后缀，比如 github.com/user/lib/v2。这不是风格问题，是 Go 解析器的语法规则：不加 /v2，Go 就当它是 v1 兼容版，根本不会加载 v2 的代码。
后果很直接：
- 你
go get github.com/user/lib@v2.1.0，但代码里仍写import "github.com/user/lib"→ 编译报错找不到包 - 必须改成
import "github.com/user/lib/v2"，且所有调用处都要同步改
例外只有一种：gopkg.in/yaml.v2 这类老路径，后缀用点不用斜杠，是历史兼容设计，新项目别模仿。
真正容易被忽略的，是 go.mod 里 replace 和 exclude 的作用范围——它们只影响当前模块，不传递给下游；而 go.sum 的哈希是 per-module 的，跨模块复用时不会自动继承校验值。这两点在多模块仓库或内部 SDK 场景下，经常成为 CI 构建失败的隐形源头。
