Go 1.11 的 go mod 不支持原生嵌套多模块，多个 go.mod 共存需手动协调；必须拆分的场景包括：独立发布、依赖冲突、构建约束隔离、CI/CD 模块化；合法结构要求各 go.mod 目录互不重叠且为自身模块根；跨模块导入须用 replace 或发布版本，避免路径错配与版本混乱。
Go 1.11 引入的 go mod 本身不支持“一个项目多个 module”的原生嵌套管理——所谓“多模块项目”，实际是多个独立 go.mod 文件共存的目录结构，需手动协调依赖、版本和构建边界。
什么时候必须拆成多个 module？
不是为了“分层漂亮”或“模仿 Java Maven 多模块”，而是遇到以下真实约束时才值得拆：
- 不同子目录要发布为独立可被外部
go get的包（如github.com/user/api和github.com/user/infra） - 各子模块有完全不重叠的依赖集，且某些依赖存在无法调和的版本冲突（例如一个模块强依赖
grpc-go v1.44，另一个必须用v1.60+） - 需要对部分模块启用
//go:build ignore或私有构建约束，而其他模块不能受干扰 - CI/CD 要求按模块粒度做独立测试、构建或镜像打包（如只触发
./cmd/admin的测试）
多个 go.mod 共存的合法目录结构长什么样？
Go 官方允许且明确支持“多根 module”，只要每个 go.mod 所在目录是其自身 module 的根，且彼此不重叠。典型结构如下：
myproject/ ├── go.mod <-- 主 module（可选，仅用于顶层工具链或聚合命令） ├── cmd/ │ ├── api-server/ │ │ ├── main.go │ │ └── go.mod <-- module github.com/you/myproject/cmd/api-server │ └── worker/ │ ├── main.go │ └── go.mod <-- module github.com/you/myproject/cmd/worker ├── internal/ │ └── auth/ <-- 不含 go.mod：internal 包只能被同 module 引用 ├── pkg/ │ ├── api/ <-- 含 go.mod：module github.com/you/myproject/pkg/api │ │ ├── v1/ │ │ └── go.mod │ └── util/ <-- 含 go.mod：module github.com/you/myproject/pkg/util └── go.sum
关键规则：go mod 命令总是以当前工作目录下的 go.mod 为准；go build 在无 -modfile 时也只读取当前目录或向上最近的 go.mod。
立即学习“go语言免费学习笔记（深入）”；
如何避免跨 module 导入失败或版本错乱？
当 cmd/api-server 想用 pkg/api 时，不能写 import "github.com/you/myproject/pkg/api" 然后指望本地路径自动映射——Go 不做软链接式解析。必须显式处理：
- 发布
pkg/api到公开或私有 Go proxy，并在cmd/api-server/go.mod中require github.com/you/myproject/pkg/api v0.1.0 - 开发阶段快速验证：在
cmd/api-server/go.mod中用replace指向本地路径：replace github.com/you/myproject/pkg/api => ../pkg/api -
禁止在
replace后忘记删掉再发布——这会导致下游用户go get失败 - 若两个 module 都依赖同一第三方库但版本不同，Go 会按主 module 的
go.sum锁定一个版本，可能引发运行时 panic；此时应统一升级或引入中间适配层隔离
常见报错与定位方式
遇到构建失败，先看错误是否含以下关键词：
-
cannot find module providing package xxx→ 当前目录无go.mod，或 import path 与module声明不匹配（检查go.mod第一行module github.com/xxx是否和 import 路径一致） -
found modules in multiple directories→go命令在当前目录及父目录都发现了go.mod，cd 进具体子模块目录再执行命令 -
missing go.sum entry→ 该 module 的go.sum缺失对应行，运行go mod tidy从当前go.mod重新生成 -
invalid version: unknown revision→replace指向的本地路径不存在，或 Git 仓库未提交/未打 tag
最易被忽略的是：每个 go.mod 都要单独 go mod tidy，不能只在项目根目录跑一次就认为万事大吉。
