完全合法，go 1.12+ 明确支持多模块模式；每个 go.mod 只要位于无外层 go.mod 的目录中，即被视为独立模块，但需确保模块路径唯一、replace 配置正确且 go111module=on。
多个 go.mod 文件共存是否合法？
完全合法，且是 Go 1.12+ 明确支持的多模块模式。关键不是“能不能放多个”，而是“每个 go.mod 是否被正确识别为独立模块”。Go 工具链通过目录层级和 go mod init 的调用位置决定模块边界——只要某个目录下有 go.mod，且其父目录没有更外层的 go.mod（或父级 go.mod 未将该目录纳入 replace 或 require），它就被视为一个独立模块。
常见误操作：
- 在根目录执行 go mod init 后，又在子目录重复执行，却不清理子目录的 go.mod → 导致子包被当成外部依赖，go build 报 cannot find module providing package
- 手动复制 go.mod 而非用 go mod init example.com/submod 初始化 → 模块路径错误，本地 import 无法解析
- 每个模块必须有唯一、可解析的模块路径（如
github.com/yourname/project/api） - 子模块若需引用同项目其他模块，应在自身
go.mod中用replace指向本地路径，例如：replace github.com/yourname/project/core => ../core
- CI 构建时需确保
replace不生效（可通过GOFLAGS="-mod=readonly"控制）
如何让主模块正确加载本地子模块？
核心是控制 go list 和 go build 对依赖路径的解析顺序。默认情况下，Go 优先查 require 声明的版本，再查 replace，最后才尝试本地文件系统。所以仅写 require github.com/yourname/project/api v0.0.0 是不够的。
实操建议：
- 在主模块的 go.mod 中显式添加 replace，指向相对路径（不是绝对路径）：
replace github.com/yourname/project/api => ./api
- 子模块自己的
go.mod 中，module 行必须与 replace 左侧完全一致（包括大小写和斜杠方向）
- 运行 go mod tidy 后检查 go.sum：若出现 github.com/yourname/project/api v0.0.0-00010101000000-000000000000 h1:... 这类伪版本，说明 replace 生效；若仍是远程哈希，则 replace 未命中
- 避免在
replace中使用../跨出当前模块根目录，否则go build可能报invalid replace directive: .. is not a valid module path element - 如果子模块尚未发布到远程仓库，不要删掉
replace后直接go mod tidy—— 它会去 proxy 拉取不存在的版本，失败后自动退回到 pseudo-version，但 import 路径仍无法解析
为什么 go run ./cmd/... 会找不到子包？
因为 go run 默认以当前目录为模块根，只识别本目录下的 go.mod。当你在项目根目录执行 go run ./cmd/app，Go 会加载根目录的 go.mod；但如果 cmd/app 内部 import 了 github.com/yourname/project/api，而该路径未在根模块的 require 或 replace 中声明，就会失败。
两种解法：
- 方案一（推荐）：把所有命令行入口保留在主模块内，子模块只提供库，不放 main 函数
- 方案二：为每个含 main 的子目录单独初始化模块，并在其中 require 其他本地模块（配合 replace）
- 切勿在
cmd/下直接go mod init并设module cmd/app—— 这会导致 import 路径变成cmd/app，无法被其他模块引用 - 如果坚持分模块管理命令，每个
cmd/xxx应有自己的go.mod，module设为完整路径如github.com/yourname/project/cmd/app，并用replace关联内部依赖 -
go run不支持跨模块自动推导replace，必须确保运行时所在目录的go.mod已声明全部依赖
构建多模块项目时容易忽略的 GOPATH 和 GO111MODULE 行为
Go 1.16+ 默认开启 GO111MODULE=on，但某些旧脚本或 Dockerfile 里仍显式设为 auto 或 off，会导致 go build 忽略 go.mod，回退到 GOPATH 模式，进而无法识别本地 replace 和多模块结构。
立即学习“go语言免费学习笔记（深入）”；
验证方式：
- 运行 go env GO111MODULE，必须是 on
- 运行 go env GOPATH，若输出非空，注意：GOPATH 不影响模块行为，但 go get 在 GO111MODULE=on 时不会写入 GOPATH/src，所有依赖都进 vendor 或 pkg/mod
- Docker 构建中常漏掉
ENV GO111MODULE=on，导致go build报no Go files in ...（其实是没读go.mod） - Windows 下路径分隔符不影响
replace解析，但./sub和.\sub在go.mod中都应写作./sub（Go 规范要求 POSIX 风格） - 模块路径中的
v2、v3等版本后缀不是必须的，但一旦加了，就必须在所有引用处保持一致，否则go mod tidy会当作不同模块处理
模块路径拼写、replace 范围、GO111MODULE 状态这三点，错一个就卡住整个多模块链路。调试时优先检查 go mod graph | grep yourmodule 输出是否包含预期的本地映射。
