replace 必须写在 go.mod 文件中，只对当前模块生效，不能通过命令行参数或环境变量覆盖；本地替换需确保路径、go.mod 和 module 名三者完全一致。
replace 写在哪？go.mod 里必须这样放才生效
replace 必须写在 go.mod 文件中，且只对当前模块起作用——它不是命令行参数，也不是构建时开关，go run 或 go build 加任何 flag 都无法临时覆盖依赖。
常见错误是以为能用 GOFLAGS="-mod=replace=..." 或类似方式绕过，实际完全无效。Go 模块系统不支持运行时路径重定向。
-
replace可放在require块前或后，顺序不影响功能，但同一旧路径只认第一个声明 - 左边路径（
old/module/path）必须和代码里import的路径、以及require行中的路径**完全一致**：大小写、末尾斜杠、版本后缀（如@v1.2.0）都不能差 - 右边如果是本地路径（如
./utils），必须是相对于go.mod所在目录的相对路径，且该目录下必须有合法的go.mod文件，其中module名需与左边路径匹配
本地替换怎么写？路径、go.mod、module 名三者必须对齐
想用本地改好的 github.com/myorg/logic 替换线上版本，最常卡在“写了 replace 却还是拉远程”，根本原因是三处没对上：路径算错、本地没 go.mod、或 module 名写成了 logic 而不是完整路径。
实操步骤很简单，但每步都不可跳过：
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 在本地库根目录运行
go mod init github.com/myorg/logic（module 名必须和 replace 左边完全一致） - 确认主项目
go.mod中写的是replace github.com/myorg/logic => ../logic（不是./logic，也不是绝对路径，除非你明确要那样写） - 运行
go mod tidy—— 它会自动把该依赖标记为// indirect或更新require行，并验证本地路径可读 - 用
go list -m -f '{{.Replace}}' github.com/myorg/logic检查输出是否为../logic，这是唯一靠谱的验证方式
远程 fork / 分支怎么替？别漏伪版本，否则 go mod tidy 会失败
用自己 fork 的 github.com/you/httpclient 替换原版时，如果右边只写 github.com/you/httpclient main，go mod tidy 很可能报错：no matching versions for query "latest" —— 因为 Go 默认需要确定的版本锚点。
正确做法是提供一个可解析的版本标识，优先级从高到低：
- 已打 tag 的版本：
replace github.com/original/httpclient => github.com/you/httpclient v1.5.2 - 某次 commit 的伪版本（推荐查出来再填）：
go list -m -versions github.com/you/httpclient或直接用v0.0.0-20240501120000-abcdef123456 - 分支名（仅限 Git 仓库，且需确保该分支有
go.mod）：replace github.com/original/httpclient => github.com/you/httpclient fix-timeout
注意：fix-timeout 这种写法不会自动取最新 commit，而是按 Git 的 ref 解析；如果分支没更新，本地也不会感知，容易误判。
为什么改了 replace 还不生效？缓存、路径、继承性三个坑最致命
最典型的“改了不生效”，90% 是因为缓存没清、路径算错、或误以为 replace 会透传给子模块。
-
go mod download后模块已缓存在$GOPATH/pkg/mod，即使改了go.mod，Go 仍可能复用旧缓存 —— 必须执行go clean -modcache再go mod tidy - 本地路径写成
../utils/（带斜杠）或utils（缺./），Go 会直接忽略，不报错也不生效 -
replace不会被下游模块继承：如果你的myapp用了 replace，而别人require myapp，他们构建时仍会拉原始依赖，不会看到你的重定向
上线前务必移除或注释掉所有 replace 行，CI 环境中若工作区没有对应本地路径，构建必然失败。这不是“建议”，是硬性约束。
