答案：replace必须写在当前项目go.mod中才生效，不能写在被替换模块的go.mod里；验证方式为go list -m -f '{{.replace}}' module，三要素（路径、本地go.mod、module名）须完全一致。
replace 必须写在当前项目的 go.mod 里才生效
很多人写了 replace 却没生效，第一反应是“语法错了”，其实八成是写错了位置——replace 只对声明它的模块起作用，不能写在被替换依赖自己的 go.mod 中。比如你项目依赖 github.com/a/b，想用本地改好的版本，就得把 replace 行加到你自己项目的 go.mod 里，而不是跑到 github.com/a/b 的代码里去改。
验证是否生效最可靠的方式是运行：
go list -m -f '{{.Replace}}' github.com/a/b
输出非空（比如 ../local-b）才说明真替换了。如果输出空，要么路径没对上，要么根本没写对地方。
本地路径替换三要素必须完全一致
本地替换失败的典型表现：go mod tidy 不报错，但编译时还是拉远程、或者提示 cannot find module。核心原因是三处没对齐：
-
replace左边的模块路径（如github.com/a/b）必须和require行里写的、以及代码中import的路径完全一致（大小写、斜杠、版本后缀都不能差） - 右边的本地路径（如
../local-b）必须是相对于当前项目go.mod所在目录的相对路径 - 本地目录下必须有
go.mod文件，且其中module声明必须和左边路径完全相同（不能简写成b或local-b）
常见错误：replace github.com/a/b => ./b —— 如果 ./b 目录里 go.mod 写的是 module b，Go 就会拒绝加载。
replace 指向远程分支或 fork 的写法与限制
想用自己 fork 的分支做临时替换，语法是：
replace github.com/original/repo => github.com/yourname/repo v1.2.3-fix
注意几点：
- 目标仓库必须有合法的
go.mod，且module名与左边一致 -
v1.2.3-fix是 Git tag 或 branch 名，不是 Go 版本号；如果分支名含斜杠（如fix/abc），要用引号包住："fix/abc" - 这种写法仍走 proxy 流程，所以要确保该 commit 在目标仓库存在，否则
go build会报missing go.sum entry - 不能省略版本部分，写成
=> github.com/yourname/repo是无效的
CI 和多环境部署时 replace 的坑
指向本地路径的 replace（如 => ../utils）在 CI 环境大概率直接失败，因为路径不存在。这不是 bug，而是设计使然——replace 是开发期便利机制，不是部署方案。
安全做法：
- 用
.gitignore忽略临时replace行，或只在开发分支保留 - CI 构建前先运行
go mod edit -dropreplace=github.com/a/b清掉本地替换 - 长期需要私有依赖，应配置 GOPROXY 或用
go workspaces管理多模块，而非依赖replace
真正容易被忽略的是：即使你没提交 replace，只要它存在于本地 go.mod，go build 就会按它走——构建机器上残留的开发配置比想象中更常见。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
