replace必须写在主项目go.mod文件末尾require块之后，仅对当前模块生效且不被下游继承；左边路径须与import完全一致，右边本地路径须以./开头并含匹配module名的go.mod文件。
replace 写在 go.mod 里才生效，不是命令行参数
很多人以为 go mod replace 是个可直接运行的命令，其实它只是 go mod edit 的子命令，真正起作用的是写进 go.mod 文件里的 replace 语句。工具链只在解析依赖时读取该文件，且仅对当前模块生效——下游模块不会继承这个替换。
常见错误是把 replace 写进被替换模块自己的 go.mod，比如你 fork 了 github.com/sirupsen/logrus 并在它的 go.mod 里加了 replace，这完全无效。必须写在你**主项目的 go.mod 文件末尾、require 块之后**。
-
replace行不能嵌在require或exclude块内，否则会被忽略 - 左边路径（
old/module/path）必须和import语句里一模一样，包括大小写、末尾斜杠、版本后缀（如v2） - 右边如果是本地路径，必须以
./开头，且该目录下要有合法的go.mod，其中module名必须与左边完全一致
用 go mod edit -replace 自动生成配置，避免手误
手动编辑 go.mod 容易漏掉换行或空格，推荐用 go mod edit 命令生成。它会自动格式化、校验语法，并写入正确位置。
例如把远程依赖替换成本地路径：
立即学习“go语言免费学习笔记（深入）”；
go mod edit -replace=github.com/sirupsen/logrus=./local/logrus
替换成另一个远程仓库加版本：
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
go mod edit -replace=github.com/sirupsen/logrus=github.com/myorg/logrus v1.9.3
- 执行后不会立即生效，必须跟
go mod tidy才会更新go.sum和构建缓存 - 如果提示
invalid module path，说明右边本地路径不存在或没go.mod -
go mod edit -print可预览修改结果，避免误操作
指向本地路径时，模块名一致性是硬性门槛
本地替换失败最常卡在这一步：你 clone 了一个库到 ./local/logrus，但它的 go.mod 第一行写的是 module github.com/Sirupsen/logrus（首字母大写），而你的 import 是 github.com/sirupsen/logrus（全小写）。Go 认为这是两个不同模块，replace 不匹配。
解决方法只有两个：
- 改本地库的
go.mod中module行，使其与import路径严格一致 - 或者改代码里的
import，保持大小写、拼写、斜杠全部一致
注意：go mod init 生成的默认 module 名可能带错大小写，务必手动核对。空的或只有 module xxx 没其他内容的 go.mod 也算合法，但必须存在。
CI/部署环境里 replace ./xxx 会直接失败
本地开发时用 replace github.com/x/y => ./local/y 很方便，但提交到 Git 后，CI 流水线或生产服务器上根本不存在 ./local/y 这个路径，go build 直接报错 cannot find module。
这不是 bug，是 Go 的设计约束：本地路径替换只用于开发期，不适用于部署。
- CI 前必须移除所有
./xxx类型的replace，改用真实远程地址 + 版本号 - 私有模块应走
GOPROXY配置，而不是靠replace硬编码路径 - 若真需多环境差异化，用
go work或构建 tag + 条件编译，而非依赖replace
最容易被忽略的一点：replace 不影响 go list -m all 的输出，但它决定 go build 实际加载哪份代码——调试时别只看列表，要验证实际运行逻辑是否走到了本地路径。
