Go多模块项目依赖统一靠根模块锚定版本，而非各子模块自治；因构建时依赖图被压平，若子模块require不同版本会引发冲突或panic，必须由根go.mod显式声明并管控第三方依赖。
多模块项目里依赖版本不统一，不是靠“锁住所有子模块的 go.mod”实现的，而是靠主模块（根模块）做版本锚点——它不写业务代码，只管“谁该用哪个版本”。
为什么不能每个子模块各自管自己的 require？
因为 Go 的构建系统最终会把整个依赖图压平成一个版本集合。如果 service 模块 require github.com/some/lib v1.5.0，而 data 模块 require v1.8.0，Go 会选 v1.8.0；但如果 data 又 require 了另一个强制要 v2.0.0 的包，而 service 还卡在 v1.x，就会触发编译失败或运行时 panic。
常见错误现象：undefined: somepkg.SomeFunc 或 cannot use ... (type v2.SomeType) as type v1.SomeType —— 这说明两个模块实际加载的是不同 major 版本的同一库，且路径没做 /v2 分隔。
- 子模块各自升级依赖，但没人同步到根模块 → 各自构建 OK，合起来跑就崩
- CI 中在根目录执行
go build ./...，却没检查各子模块是否都兼容当前解析出的版本 - 用
go get -u升级某个子模块的依赖，结果把根模块的require行漏掉了
怎么用根模块做版本锚点？
在项目根目录建一个纯管理用的 go.mod，模块名建议和组织域名一致（如 example.com/project），里面只干三件事：声明依赖、用 replace 指向本地子模块、不放任何 .go 文件。
立即学习“go语言免费学习笔记（深入）”；
示例根 go.mod：
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
module example.com/project
go 1.21
require (
example.com/project/service v0.0.0
example.com/project/data v0.0.0
github.com/sirupsen/logrus v1.9.3
)
replace example.com/project/service => ./service
replace example.com/project/data => ./data
-
require行必须显式列出所有子模块，哪怕它们还没发版 —— 这样go mod tidy才能感知并校验版本一致性 -
replace只在开发期生效；发布前删掉，打 tag 后go mod tidy会自动把v0.0.0升级为真实语义化版本（如v0.3.1） - 关键第三方依赖（如 logrus、gin）直接写死在根
go.mod中，不交给子模块自己定 —— 避免 service 用 v1.9.3、data 用 v1.8.1
怎么验证所有子模块其实用了同一个版本？
别只信 go list -m all 的输出，它显示的是“最终被选中的版本”，但你看不到谁在拉旧版。真正要查的是“谁在拖后腿”。
进根目录后运行：
-
go list -m -f '{{.Path}} {{.Version}}' all | grep logrus—— 看 logrus 最终选了哪个版本 -
go mod graph | grep logrus—— 找出哪些模块直接 require 了它 -
go mod why -m github.com/sirupsen/logrus—— 查清某条 import 路径为何引入这个版本
如果发现 service 和 data 都出现在 go mod graph 输出里，但各自 require 的版本不同，说明它们没走根模块的锚点控制 —— 得去它们各自的 go.mod 里删掉对 logrus 的 require，只留根模块那一份。
go.work 能替代根模块吗？
不能。工作区（go.work）适合快速并行开发多个独立模块，但它不参与版本锁定，也不生成 go.sum，更不会帮你统一第三方依赖版本。它只是让 go build 和 go test 能跨目录执行，底层仍靠各子模块自己的 go.mod 解析依赖。
也就是说：go.work 解决的是“怎么一起跑多个模块”，而根模块解决的是“怎么确保它们用同一套依赖”。两者可以共存，但职责不能混。如果你只建了 go.work 却没设根 go.mod，那各子模块依然可能悄悄拉不同版本的 golang.org/x/net 或 google.golang.org/protobuf，上线前才暴露问题。
最容易被忽略的一点：根模块的 go.sum 不覆盖子模块的校验和 —— 每个子模块仍保留自己的 go.sum，所以 CI 构建时一定要进子模块目录执行 go build，而不是只在根目录 run 一遍完事。
