go mod replace是go模块原生支持的路径重定向机制，仅在当前模块生效，用于主模块引用本地子模块；需确保子模块含go.mod且module名与replace左侧完全一致，ci前必须移除。
多模块项目里，Go 默认不自动识别同级或子目录下的其他 go.mod，直接 import 会报 cannot load: module is not a dependency of module——这不是 bug，是 Go 模块加载机制的明确行为：它只向上查找最近的一个 go.mod，不会跨目录发现并链接兄弟模块。
主模块如何引用本地子模块
必须用 replace 指令做路径映射，这是开发阶段唯一可靠的方式。
-
replace不是“临时 hack”，而是 Go Module 原生支持的依赖重定向机制；它让go build和go test在编译时跳过远程解析，直接读取本地文件系统路径 - 主模块（如
github.com/yourorg/app）的go.mod中添加：replace github.com/yourorg/lib => ./lib -
./lib必须是完整模块目录，含自己的go.mod，且其中module声明必须与replace左侧完全一致（包括大小写和路径） - 执行
go mod tidy后，运行go list -m all | grep lib应看到类似github.com/yourorg/lib => ./lib的输出，表示生效 - CI 构建前务必删除
replace行，否则构建失败；建议在 CI 脚本开头加GOFLAGS="-mod=readonly" go mod tidy提前暴露问题
为什么出现 import cycle not allowed
这不是模块配置问题，是包级导入链断裂失败。模块边界无法切断已存在的循环引用。
- 典型场景：模块 A 的
pkg/authimport 模块 B 的pkg/db，而 B 又 import A 的pkg/errors - 用
go mod graph | grep yourmodule或go list -f '{{.Deps}}' ./...查实际依赖链，比猜更快 - 解法不是删 import，而是抽离共享内容（如错误码、常量、基础类型）到独立的
github.com/yourorg/shared模块，并在 A、B 中都replace它 - 严禁把共享代码放在
internal/下跨模块复用——internal对其他模块不可见，强行 import 会直接失败
go.sum 不一致导致 CI 构建失败
每个模块的 go.sum 是独立校验文件，不能合并、不能忽略、也不能靠主模块一次 tidy 同步。
- 子模块更新依赖后，若主模块没重新
go mod tidy，主模块的go.sum就缺对应 checksum，CI 报missing go.sum entry - CI 流程中，必须对每个含
go.mod的目录单独执行go mod tidy，顺序建议：先cd ./lib && go mod tidy && cd -，再处理主模块 - 构建前加
go mod verify，它会检查所有模块的 checksum 是否匹配，比等go build报错更早发现问题 - 私有仓库（如
git.company.com/internal/lib）必须配置GOPRIVATE=git.company.com/*，否则go mod download会走 proxy 并 404
最易被忽略的一点：replace 只在当前模块作用域生效，子模块里的 replace 不会影响主模块；如果多个子模块都依赖同一个内部库，每个地方都要单独 replace，没有“全局替换”机制。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
