replace必须写在当前主模块的go.mod中而非被替换依赖自己的go.mod里，否则无效；右侧本地路径需以./开头、含匹配module名的go.mod文件，且间接依赖需手动顶层replace覆盖。
replace 写在了被替换模块自己的 go.mod 里
这是最常被忽略的根源：replace 必须写在当前主模块的 go.mod 中，而不是你 fork 或修改的那个依赖包自己的 go.mod 里。Go 的 replace 规则只对声明它的模块及其下游生效，无法“反向注入”到上游依赖中。
常见错误现象：go list -m all 仍显示远程路径、go build 拉的还是远端代码、IDE 提示没变化——八成是 replace 被错贴进了 ./vendor/github.com/some/lib/go.mod 或你 clone 下来的本地库目录里。
- 打开你项目根目录下的
go.mod，确认 replace 行在require块之后、文件末尾 - 删掉所有被替换模块自己目录里的 replace 语句（它们完全无效）
- 执行
go mod tidy强制刷新依赖图和go.sum
本地路径不合法或模块名不匹配
replace github.com/foo/bar => ./local-bar 这条语句看似简单，但右侧路径和左侧模块名必须同时满足三个硬性条件，缺一不可：
- 右侧路径必须是以
./开头的相对路径（不能是~/、/abs/path或../sibling） -
./local-bar目录下必须存在go.mod文件，且其第一行module声明必须与 replace 左侧完全一致（包括大小写、版本后缀，如v1.2.3） - 该
go.mod不能是空的：至少含一个require或已执行过go mod init并有实际代码
例如：replace github.com/foo/bar => ./bar，那么 ./bar/go.mod 第一行必须是 module github.com/foo/bar，不是 module bar，也不是 module github.com/foo/bar/v2。
立即学习“go语言免费学习笔记（深入）”；
间接依赖没被顶层 replace 覆盖
如果你没直接 import "github.com/x/y"，而是通过某个第三方库间接引入它，那仅在主模块 go.mod 里写 replace 是不够的——Go 不会自动穿透到间接依赖链里做映射。
实操步骤：
- 先用
go mod graph | grep github.com/x/y查出谁引入了它（比如github.com/other/pkg） - 再运行
go mod edit -replace=github.com/x/y=./local-y（确保写进主模块go.mod） - 执行
go mod tidy，观察输出是否提示 “replaced github.com/x/y => ./local-y” - 验证：
go list -m github.com/x/y应返回./local-y而非远程地址
CI 或部署时本地路径失效
replace 指向 ./local-path 是开发期便利机制，不是部署方案。CI 机器上不存在这个路径，go build 会直接失败，这不是 bug，是设计使然。
解决思路分场景：
- 调试阶段：用
go clean -cache -modcache清除缓存，避免旧构建产物干扰 - CI 阶段：移除所有
./xxx类 replace；改用远程 tag 替换（如replace github.com/x/y => github.com/myfork/y v0.1.0），并确保该 tag 已推送到可访问仓库 - 多环境统一：把本地修改打成正式 tag 推送，让所有环境拉同一 commit，而非靠 replace 维持差异
真正容易被忽略的是：replace 后改了本地代码，但没清 $GOCACHE 和 $GOMODCACHE，编译器仍复用旧 object 文件——看着像没生效，其实是缓存问题。
