replace必须写在主项目go.mod中，仅对该模块生效；需确保左右路径逐字匹配、本地路径存在且含正确module声明，并执行go mod tidy验证。
replace 必须写在当前项目的 go.mod 里，不是被替换模块的
很多人把 replace 错误地加到被替换库自己的 go.mod 文件里，结果毫无效果。Go 的 replace 是单向、局部的：它只对声明它的模块生效，且仅影响该模块及其构建过程，不会“注入”到下游依赖中。
常见错误现象：
-
go build仍拉远程包，go list -m all显示没变 - 本地改了代码，运行时行为没更新
正确做法：
- 打开你**主项目**的
go.mod（即执行go run或go build的那个目录下的文件） - 在任意位置（
require块前后都行）添加replace github.com/xxx/yyy => ../local-yyy - 确保路径是相对于这个
go.mod所在目录的
本地路径替换三要素必须全部对齐
写了 replace 却还是走线上？大概率卡在这三处不一致：
立即学习“go语言免费学习笔记（深入）”；
-
replace左边的模块路径（如github.com/myorg/logic）必须和你代码里import的路径、以及require行中的路径**逐字匹配**：大小写、末尾斜杠、@vX.Y.Z后缀都不能差 - 右边本地路径（如
../logic）必须存在，且该目录下有go.mod文件 - 那个本地
go.mod里的module声明必须和左边路径完全一致（例如不能写成module logic，而必须是module github.com/myorg/logic）
验证是否对齐最直接的方式是：
go list -m -f '{{.Replace}}' github.com/myorg/logic
输出应为 ../logic；如果为空或报错，说明没生效。
go mod tidy 不是可选步骤，而是强制验证环节
go mod tidy 不只是整理依赖列表，它会实际尝试读取 replace 指向的本地路径、校验其 go.mod、更新 go.sum 并修正 require 行状态（比如标上 // indirect）。跳过这步，replace 很可能只是“纸上谈兵”。
执行后注意检查：
- 是否报错
no matching versions或cannot find module—— 这说明本地路径不可读或go.mod缺失/错配 -
go.sum是否新增了对应条目（内容来自本地路径，不是远程 hash） -
go.mod中require行是否保留原版本号（replace不改变语义版本，只换源）
跨平台或 CI 环境下用相对路径比绝对路径更可靠
写成 replace github.com/x/y => /home/user/src/y 在你本地能跑，但同事或 CI 机器上路径不存在，直接构建失败。这不是 bug，是设计使然 —— replace 的本地路径就是开发期便利机制，不是部署方案。
推荐做法：
- 一律使用相对于主项目
go.mod的相对路径（如../y、./vendor/y） - 团队协作时，在 README 或 CONTRIBUTING.md 里注明子模块预期存放位置
- CI 流水线中禁用
replace（可通过分支策略、环境变量条件化，或干脆删掉）
真正需要多模块协同的长期方案，应该用 go work，而不是靠一堆 replace 维持——后者容易在提交、合并、重构时漏掉或冲突，反而增加维护成本。
