go mod replace 是本地子模块依赖的唯一可靠方式，需在主模块 go.mod 中显式声明，子模块路径必须严格匹配且含独立 go.mod，replace 仅限开发阶段使用，ci 构建前须清理并同步 go.sum。
go mod replace 是本地子模块依赖的唯一可靠方式
Go 的模块系统默认只识别当前目录向上最近的 go.mod，不会自动加载同级或子目录下的其他模块。当你有 ./cli、./api、./pkg 等独立子模块时，主模块无法直接 import 它们——不是语法错误，而是构建时报 cannot load github.com/yourorg/pkg: module github.com/yourorg/pkg is not a dependency of module github.com/yourorg/app。
解决方法只有一个：在主模块的 go.mod 中显式声明 replace：
replace github.com/yourorg/pkg => ./pkg
注意三点：
-
./pkg必须是完整模块目录，含自己的go.mod（且其中module声明需与replace左侧路径一致） -
go mod tidy后，go list -m all应显示该行带=> ./pkg后缀，表示生效 -
replace仅用于开发阶段；CI 构建或发布前必须删除，否则远程构建会失败
子模块 go.mod 的 module 路径必须与 replace 左侧严格匹配
常见错误是子模块 go.mod 里写 module local/pkg，而主模块想用 replace github.com/yourorg/pkg => ./pkg ——这会导致 import 语句（如 import "github.com/yourorg/pkg"）和 replace 规则不匹配，go build 仍报错。
正确做法是保持路径一致性：
- 主模块
go.mod中：replace github.com/yourorg/pkg => ./pkg - 子模块
./pkg/go.mod中：module github.com/yourorg/pkg - 所有代码中 import 都用
"github.com/yourorg/pkg"，而非相对路径或local/前缀
模块路径本质是导入标识符，不是文件系统路径；它决定了别人怎么 import 你的代码，也决定了 replace 能否命中。
跨子模块循环依赖必须抽离共享逻辑到第三模块
当 ./cli import ./pkg，而 ./pkg 又间接 import ./cli（比如通过 error 定义、config 结构体、或测试辅助函数），就会触发 import cycle not allowed 错误。
这不是 replace 能绕过的——模块边界不切断包级循环。必须重构：
- 找出被双向引用的类型、常量、错误码等，移到新模块（如
./shared） - 为
./shared单独go mod init github.com/yourorg/shared - 在
./cli/go.mod和./pkg/go.mod中都加replace github.com/yourorg/shared => ../shared - 禁止在
internal/下放跨模块共享代码，internal对其他模块不可见
CI 构建前必须验证 replace 是否已清理 & go.sum 是否同步
本地开发时 replace 让一切看起来正常，但 CI 流水线通常设置 GOFLAGS="-mod=readonly"，遇到 replace 直接报错退出；更隐蔽的问题是子模块更新了依赖但没运行 go mod tidy，导致主模块的 go.sum 缺失校验和，go build 失败并提示 checksum mismatch 或 missing go.sum entry。
建议 CI 脚本中加入这两步：
grep -q "replace" go.mod && echo "ERROR: replace still present" && exit 1for d in cli api pkg; do [ -d "$d" ] && (cd "$d" && go mod tidy); done
真正麻烦的从来不是写 replace，而是确保它只活在开发环境里，且所有子模块的依赖状态始终对齐——这点容易被忽略，直到 PR 检查失败才暴露。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
