replace必须写在当前项目根目录的go.mod中才生效，不能写在被替换模块自己的go.mod里；本地路径需以./开头且目标目录必须有go.mod；间接依赖须先通过go get拉入require再replace；go mod tidy是使replace生效的关键步骤。
replace 必须写在当前项目的 go.mod 里
很多人加了 replace 却没生效，第一反应是语法错了，其实大概率是写错位置了。它不能写在被替换模块自己的 go.mod 中，只对声明它的模块及其直接构建行为生效——也就是说，必须放在你正在开发的那个项目的根目录 go.mod 文件里。
常见错误：
- 把
replace github.com/a/b => ./local-b写进./local-b/go.mod—— 这完全无效，Go 不会向上查找 - 在子模块里写了
replace，但主项目没引用该子模块的require行 —— 主项目构建时根本看不到这条规则 - 用
go mod edit -replace=...修改后没保存，或没执行后续命令
本地路径替换必须带 ./ 前缀且目标有 go.mod
replace 指向本地目录时，路径不是“能访问就行”，而是要满足两个硬性条件：相对路径以 ./ 开头，且该目录下必须存在合法的 go.mod（哪怕只有 module local-name 一行）。
否则 Go 会 fallback 到 legacy mode 加载，忽略 replace 规则，甚至报 cannot find module providing package。
立即学习“go语言免费学习笔记（深入）”；
正确写法示例：
replace github.com/user/lib => ./lib
错误写法（全部失效）：
-
replace github.com/user/lib => lib（缺./） -
replace github.com/user/lib => ./lib/（末尾斜杠） -
replace github.com/user/lib => /home/me/lib（绝对路径，CI 环境必然失败） -
./lib目录下没有go.mod
间接依赖必须先显式拉进 require 才能 replace
如果某个模块是你项目里某第三方库引入的（即标记为 // indirect），你不能直接对它写 replace —— Go 会无视这条规则，因为该模块不在你的直接依赖树中。
得先让它“浮上来”：
- 运行
go mod graph | grep target-module查它由谁引入 - 用
go get target-module@latest或go get target-module@v1.2.3强制拉进require（哪怕只是临时） - 再加
replace，然后go mod tidy
否则 go build 依然加载原始版本，replace 形同虚设。
go mod tidy 不是可选步骤，而是生效关键
replace 写进 go.mod 只是声明，真正让构建系统识别、更新 go.sum、刷新缓存、重算依赖图，全靠 go mod tidy。
漏掉这步的典型现象：
-
go build报错说找不到符号，但./lib里明明有 -
go list -m all仍显示旧版本路径 - IDE（如 Goland）不识别新代码，提示 unresolved reference
顺带提醒：go mod tidy 会自动清理未使用的 require，但不会删掉 replace 行 —— 它只管依赖一致性，不管你的调试意图。
最后一点容易被忽略：本地 replace 在 CI 或其他机器上天然失效，因为 ./lib 路径不存在。这不是 bug，是设计使然 —— 它只服务于本地开发闭环，别把它当部署方案。
