Go 1.12+ 多模块仓库合法结构是子目录各自定义独立 go.mod，且 module 路径须与 import 路径一致；典型结构含主模块根目录 go.mod 和 cmd/、pkg/ 下的子模块 go.mod，internal/ 下不设 go.mod。
Go 1.12+ 多模块仓库的合法结构是怎样的
Go 官方不支持“一个仓库多个 go.mod 文件共存于同一级目录”，但允许在子目录中各自定义独立模块。只要每个 go.mod 文件所在目录是该模块的根（即 module 声明的路径能通过相对路径从该目录解析），就合法。
典型合规结构：
myorg/repo/
├── go.mod # 主模块：github.com/myorg/repo
├── cmd/
│ ├── api-server/
│ │ └── go.mod # 子模块：github.com/myorg/repo/cmd/api-server
│ └── worker/
│ └── go.mod # 子模块：github.com/myorg/repo/cmd/worker
├── internal/
│ └── utils/ # 不可被外部 import，无需 go.mod
└── pkg/
└── storage/ # 可导出子库，可配独立 go.mod（如需不同依赖版本）关键点：go mod init 时模块路径必须与实际 import 路径一致；否则 go build 或 go get 会失败。
什么时候该为子目录单独建 go.mod
不是所有子目录都需要自己的 go.mod。只有当它满足以下至少一项时才值得拆：
立即学习“go语言免费学习笔记（深入）”；
- 需要使用与主模块不同的依赖版本（例如
pkg/storage依赖cloud.google.com/go@v0.110.0，而主模块锁在v0.105.0） - 要作为独立可发布的库被其他项目
go get（此时模块路径应为github.com/myorg/repo/pkg/storage） - 存在跨模块的 cyclic import 风险，且你希望用模块边界强制隔离
- CI/CD 中需单独测试或构建（如
cd pkg/storage && go test）
反例：仅为了“看起来更清晰”而在 internal/handler 下加 go.mod —— 这会导致 go list -m all 输出混乱，且无法被主模块直接 import（Go 拒绝 import 同一仓库内其他模块的 internal 包）。
go.work 文件如何协调多模块开发
当你本地同时修改主模块和某个子模块（比如 cmd/api-server 和 pkg/storage），又不想反复 go mod edit -replace，go.work 是唯一推荐方式。
在仓库根目录运行：
go work init go work use . go work use ./pkg/storage go work use ./cmd/api-server
这会生成 go.work 文件，内容类似：
go 1.21 <p>use ( . ./pkg/storage ./cmd/api-server )
此后在任意子目录执行 go run、go test，都会按 go.work 中声明的路径解析模块，跳过 proxy.golang.org 拉取本地代码。注意：go.work 不提交到 CI，仅用于本地开发协同。
常见错误：import 路径与模块路径不匹配
这是多模块仓库最常导致 import cycle not allowed 或 cannot find module providing package 的原因。
检查步骤：
- 确认
import "github.com/myorg/repo/pkg/storage"对应的目录下go.mod第一行是module github.com/myorg/repo/pkg/storage - 如果子模块路径用了 v2+ 版本（如
module github.com/myorg/repo/pkg/storage/v2），则 import 必须带/v2 - 主模块的
go.mod中不能出现replace github.com/myorg/repo/pkg/storage => ./pkg/storage—— 这会破坏模块一致性，且go.work已提供更干净的替代方案
真正棘手的是混合使用 replace 和 go.work：Go 会优先用 replace，导致 go.work 失效，而且错误提示极不直观。
