主模块正确引用本地子模块的关键是用replace指令显式映射路径并确保模块声明严格匹配，即replace github.com/yourorg/shared => ./shared，且子模块go.mod中module名须完全一致，运行go mod tidy后通过go list -m all验证生效。
主模块如何正确引用本地多子目录模块
关键不是“能不能”，而是路径和模块声明必须严格匹配。Go 不会自动扫描子目录下的 go.mod，它只认当前命令执行位置向上最近的那个——所以如果你的子模块（比如 ./shared）里有 go.mod，但主模块没显式告诉 Go “这个路径对应哪个模块名”，就会报 cannot load: module is not a dependency of module。
实操建议：
- 确保子模块根目录下有有效的
go.mod，且module声明与你打算在代码中 import 的路径完全一致（例如module github.com/yourorg/shared） - 主模块的
go.mod中用replace显式映射：replace github.com/yourorg/shared => ./shared -
./shared是相对于主模块go.mod的路径，不是相对于 shell 当前工作目录；如果子模块在上层目录，就得写成../shared - 运行
go mod tidy后，用go list -m all | grep shared确认是否显示=> ./shared，否则说明未生效
子目录里的包怎么被外部模块 import
子目录本身不是模块，只是包（package）。只要子模块的 go.mod 声明了完整模块路径（如 github.com/yourorg/shared），它内部的任意子目录都可以作为包被 import，路径就是模块路径 + 目录名。
例如：
立即学习“go语言免费学习笔记（深入）”；
shared/
├── go.mod // module github.com/yourorg/shared
├── utils.go // package shared
└── db/
└── client.go // package db
那么其他模块可以这样引用：
-
import "github.com/yourorg/shared"→ 导入根包 -
import "github.com/yourorg/shared/db"→ 导入子包db，前提是db/client.go里写了package db - 不能写
import "./db"或import "shared/db"—— 必须用完整模块路径
为什么加了 replace 还提示 import cycle
这不是 replace 没生效，而是两个模块之间存在真实的导入环：A 模块 import B 的某个包，B 又 import A 的某个包（哪怕只是一行 import "github.com/yourorg/app/config"）。Go 的模块机制不解决包级循环，只管模块边界。
常见诱因和解法：
- 共享错误类型、常量、配置结构体，却放在了业务模块里（比如
app/errors.go被shared和service同时 import）→ 抽出独立模块github.com/yourorg/types，并在两个模块的go.mod中都replace它 - 用了
internal/目录想“复用”，但internal对其他模块不可见 → 删掉，改用真正可 export 的包 - 检查实际依赖链：
go mod graph | grep yourorg或go list -f '{{.Deps}}' github.com/yourorg/service
CI 构建失败：go.sum 不匹配或 missing entry
根本原因是各模块的 go.sum 没同步更新。主模块运行 go mod tidy 不会自动递归进子模块 tidy，而子模块自己更新依赖后，主模块仍锁着旧版本 checksum。
必须分步处理：
- 每个子模块都要单独维护自己的
go.sum—— 不要删，也不要合并到主模块 - CI 脚本里先
cd ./shared && go mod tidy && cd -，再cd ./service && go mod tidy && cd -，最后才跑主模块go mod tidy - 构建前加
go mod verify，它比go build更早暴露 checksum 不一致 - 私有仓库必须配
GOPRIVATE=git.company.com/*，否则go mod download会走 proxy 并 404
最容易被忽略的是：replace 在 CI 中默认被禁用，如果忘了删或没配 GOFLAGS="-mod=readonly"，构建时可能静默跳过依赖校验，直到 runtime 才崩。
