replace必须写在当前项目主模块的go.mod文件中且位于require块之后、文件末尾，不能嵌入require内或写在被替换包自身的go.mod中；右侧须为以./开头的相对路径，且本地包go.mod中module名须与左侧完全一致。
replace 写在哪儿才生效
replace 必须写在当前项目主模块的 go.mod 文件里，且必须位于 require 块之后、文件末尾。它不会跨模块生效——你不能把 replace 加到被替换包自己的 go.mod 里，那对你的项目完全无效。
常见错误是：把 replace 放进 require 块内部，或者放在另一个依赖模块的 go.mod 中。Go 工具链只读取当前构建上下文（即执行 go build 所在目录）下的 go.mod，其他位置的 replace 全部忽略。
-
replace github.com/user/lib => ./lib要紧接在require块结束之后，不能缩进，不能嵌套 - 如果项目用了 Go Workspaces（
go.work），replace 仍需写在子模块各自的go.mod中，go.work不支持全局 replace - IDE（如 VS Code）有时缓存旧解析结果，改完
go.mod后需手动触发 “Reload Window” 或运行go mod tidy
本地路径替换为何还是拉远端
Go 对 replace 的本地路径校验极其严格：只要任一条件不满足，就静默回退到原始依赖，不报错也不提示。
必须同时满足以下三点：
立即学习“go语言免费学习笔记（深入）”；
- 右侧路径必须是以
./开头的相对路径（比如./my-fork），不能是绝对路径或../跨父级（除非你明确知道模块根目录匹配） -
./my-fork目录下必须存在有效的go.mod文件，且其第一行module声明必须与 replace 左侧**完全一致**（含大小写、斜杠、版本后缀，如v1.2.3） - 该本地模块不能是空壳：
go.mod至少要有module行，且目录下得有可编译的 Go 文件（哪怕只有package mypackage）
验证方法：运行 go list -m github.com/user/lib，输出应为 github.com/user/lib v0.0.0-00010101000000-000000000000 => ./my-fork；若仍显示远程版本，说明上述某条未达标。
间接依赖没被 replace 到怎么办
replace 只作用于直接出现在 require 块里的模块。如果某个模块是通过第三方库引入的间接依赖（比如 A → B → C，你想替换 C），它不会自动被顶层 replace 覆盖。
解决方式只有两个：
- 先用
go mod graph | grep c-module确认它是被谁引入的，然后在你的主模块go.mod中显式require c-module vX.Y.Z，再加对应replace - 或直接在
require块中补一条require c-module v0.0.0（版本号可任意占位），再写replace—— 这样 Go 就会把它纳入解析范围
注意：go mod tidy 会自动清理掉未 import 的 require，所以补的这行必须确保代码里至少有一个 import，否则下次 tidy 就没了。
CI/部署时 replace 失效的根本原因
本地路径替换（=> ./local-path）在 CI 或生产环境必然失败，因为 ./local-path 在构建机上根本不存在。这不是 bug，是 Go 的设计预期：replace 的本地路径仅用于开发调试，不是部署机制。
上线前必须处理：
- 要么删掉所有
replace行，让依赖回归远程版本 - 要么把本地修改合并进上游，或发布正式 tag，改用
replace old => new/v1.2.3指向真实远程版本 - CI 脚本中可加检查：
grep -q "=> \./" go.mod && echo "ERROR: local replace found" && exit 1
最容易被忽略的是：即使你没手动写 replace，某些工具（如 go mod edit -replace）可能悄悄注入，务必检查 go.mod 原始内容，而不是只看 IDE 显示。
