go mod replace 必须写在项目根目录go.mod文件中require块之后，格式为replace old/path => ./local/path或绝对路径，右侧需含匹配module名的go.mod，且执行go mod tidy后才生效。
go mod replace 怎么写才生效
本地软关联的本质是用 replace 覆盖远程模块路径，让 go build 和 go test 读取你本地修改后的代码，而不是缓存里的版本。它不是“链接”，而是编译期路径重定向。
常见错误是把 replace 写在错误位置、没运行 go mod tidy、或路径写成相对路径（如 ./mylib）——Go 会把它当导入路径解析，直接报错。
-
replace必须写在项目根目录的go.mod文件里，位于require块之后、exclude之前 - 左边是原始模块路径（必须和
import语句里的一致），右边是绝对路径或相对于当前go.mod的路径（推荐用绝对路径，避免 CI 或他人拉代码时失效） - 写完后必须执行
go mod tidy，否则replace不会被加载进依赖图，go list -m all也看不到效果 - 如果本地模块本身也有
go.mod，它的module行必须和replace左边完全一致（包括大小写、斜杠方向）
为什么 go mod tidy 后 replace 没起作用
最常被忽略的是：Go 在解析 replace 时，会检查右侧路径下是否存在有效的 go.mod 文件，并且该文件的 module 声明必须匹配左侧路径。不匹配就静默忽略，不报错也不生效。
例如你在项目中 import "github.com/yourorg/utils"，想用本地 /home/me/myutils 替换，但那个目录下的 go.mod 第一行是 module github.com/yourorg/utils/v2，就会失败。
立即学习“go语言免费学习笔记（深入）”；
- 检查右侧路径的
go.mod：运行cat /path/to/local/mod/go.mod | head -n 1，确认module行与replace左侧一字不差 - 如果本地模块还没发布过，建议用伪版本号（如
v0.0.0-00010101000000-000000000000）占位，避免go mod tidy自动覆盖require行 -
replace不影响go get行为；想让别人也用你的本地版，得把replace提交进仓库，并在 README 里说明
replace 和 GOPROXY=direct 混用会怎样
不会冲突，但逻辑不同：replace 是源码级替换，GOPROXY=direct 是跳过代理直连远程仓库。两者可共存，但要注意优先级。
Go 加载依赖时，顺序是：先看 replace → 再查 GOPROXY → 最后 fallback 到 direct。所以即使设置了 GOPROXY=direct，只要 replace 匹配成功，就根本不会走网络。
- 调试阶段可以放心设
GOPROXY=direct避免代理干扰，但别依赖它替代replace - CI 环境中慎用
replace指向本地路径（如/tmp/lib），因为路径不存在会导致构建失败；应改用 git commit hash 或私有仓库地址 +replace+GOPROXY配合认证 -
replace右侧支持 git URL（如git@github.com:yourorg/utils.git），但必须配合git config或~/.netrc，否则拉不到私有库
如何验证 replace 是否真正生效
不能只看 go.mod 里有没有那行，要确认编译时实际加载的是哪个路径的源码。
- 运行
go list -m -f '{{.Dir}}' github.com/yourorg/utils，输出应该是你本地路径，而不是$GOPATH/pkg/mod/... - 在本地被替换的模块里加一句
log.Println("loaded from local")，然后跑go run main.go，看日志是否打出 - 执行
go mod graph | grep yourorg/utils，结果里应该显示yourproject => github.com/yourorg/utils，而不是带版本号的远程路径 - 如果用了
replace但go build -x日志里仍有cd $GOPATH/pkg/mod/...访问远程包，说明没生效，回退检查module名匹配和tidy
go.mod 声明、以及当前工作目录三者之间关系的严格校验。少一个字符对不上，replace 就形同虚设。 
