go mod tidy忽略子目录go.mod是因为Go只认当前工作目录向上查找的第一个go.mod作为模块根，子目录go.mod不会被自动识别，除非显式进入该目录执行命令或主模块通过正确import path引用它。
为什么 go mod tidy 会忽略子目录里的 go.mod
Go 默认只把当前目录及其父目录中最近的 go.mod 当作模块根，子目录下的 go.mod 不会被自动识别为独立模块——除非你显式进入该子目录执行命令。这是 Go 模块设计的基本规则，不是 bug，但容易误以为“子模块没生效”。
典型现象：项目结构里有 ./api/go.mod 和 ./cmd/go.mod，但在项目根目录运行 go mod tidy 后，./api 的依赖完全没出现在根 go.sum 里，甚至 go list -m all 也看不到它。
- Go 工具链只认当前工作目录所属的模块（即向上查找第一个
go.mod），不会递归扫描子目录 - 子目录模块只有被其他模块通过 import path 引用时，才会被拉入主模块的依赖图；否则就是“孤立模块”
- 如果子目录模块的 import path 和其物理路径不匹配（比如
module github.com/user/project/api但实际在./api），go命令会拒绝解析
如何让主模块正确引用子目录模块
关键不是“让 go mod tidy 扫描子目录”，而是让主模块的代码真正 import 子模块路径，并确保该路径与子模块 go.mod 中声明的 module 名一致。
- 检查子目录
go.mod第一行：module github.com/you/repo/subdir—— 这个路径必须和你在主模块里写的 import 语句完全一致，包括大小写和斜杠方向 - 在主模块代码中写
import "github.com/you/repo/subdir"，而不是import "./subdir"或import "subdir" - 子模块不能使用相对路径 import（如
import "../shared"），否则会导致构建失败或go mod tidy无法解析 - 若子模块尚未发布到远程，本地开发时可用
replace在主模块go.mod中临时映射：replace github.com/you/repo/subdir => ./subdir
go build 报错 “cannot find module providing package” 怎么定位
这个错误本质是 Go 无法根据 import path 找到对应模块，常见于子模块路径配置错误或未启用 replace。
- 运行
go list -m -f '{{.Path}} {{.Dir}}' all 2>/dev/null | grep subdir查看当前模块图中是否包含目标子模块 - 如果没输出，说明该子模块未被任何 import 触发加载，检查代码里有没有真实 import 它
- 如果输出路径不对（比如显示
github.com/you/repo/subdir但 Dir 是/tmp/gopath/pkg/mod/...），说明它被当成远程模块拉取了，而你本地修改没生效 —— 此时必须加replace - 注意
go build ./...默认只构建当前模块下的包，不会自动构建子模块；要构建子模块需明确指定路径：go build ./subdir/...
多模块项目要不要每个子目录都放 go.mod
不是必须，但仅在满足以下条件之一时才有意义：
- 该子目录要作为独立可发布的模块（例如 SDK、CLI 工具），对外提供稳定 import path
- 需要隔离依赖版本（比如
./legacy必须用旧版golang.org/x/net，而主模块用新版） - 子目录代码会被外部项目直接 import（而非仅内部调用）
否则，纯内部子包（如 ./internal/handler）没必要单独建 go.mod —— 它只是主模块的一部分，加了反而增加维护负担和潜在版本冲突。
真正容易被忽略的是：一旦加了子模块 go.mod，就必须把它当成一个“对外契约”，它的 module 路径、API 兼容性、版本标签都要按正式模块管理。很多人只图方便加了 go.mod，却没同步维护 go.mod 的 module path 和 import 使用方式，结果导致本地能跑、CI 失败、别人引用报错。
