replace未生效最常见原因是被替换模块未出现在require列表中；本地路径须以./开头；目标目录需有匹配module声明的go.mod文件。
replace 为什么加了却没生效
最常见的情况是：你改了 go.mod，执行了 go mod tidy，但 go build 还在用远程版本——不是 replace 写错了，而是 Go 没真正“认”它。
- 被替换的模块必须已出现在
require列表里（哪怕标了// indirect），否则replace是挂空挡的；可以用go list -m all | grep 模块名确认是否加载成功 - 本地路径必须以
./开头，不能是lib/或/abs/path（绝对路径虽支持但不可移植，CI 构建会失败） - 目标目录（比如
./my-fork）下必须有合法的go.mod，且里面module声明要和 replace 左侧路径完全一致（大小写、斜杠都不能差） -
go.sum不会自动更新校验和，旧记录可能残留；可手动删掉go.sum后再go mod tidy
指向本地模块时的三个硬性条件
想让 replace github.com/user/lib => ./lib 真正起作用，这三件事缺一不可：
-
./lib目录存在，且是相对于当前go.mod的路径（不是项目根目录或 GOPATH） -
./lib/go.mod文件存在，且第一行module值等于github.com/user/lib（不能少字符、不能多斜杠、不能大小写混用） - 主项目的
go.mod中已有require github.com/user/lib v1.2.3—— replace 不是“添加依赖”，而是“重定向已有依赖”
用 replace 测试 fork 分支的正确写法
别直接写 replace github.com/old/repo => github.com/you/repo master，Go 不认 master 这种模糊分支名，构建时会报错 invalid version: unknown revision master。
- 推荐写法是带明确 commit hash：
replace github.com/old/repo => github.com/you/repo v0.0.0-20260720154422-abcdef123456（用git log -n1 --format="%H" | cut -c1-12生成） - 如果目标 repo 有 tag，优先用 tag：
replace github.com/old/repo => github.com/you/repo v1.2.4-fix（前提是该 tag 在你的 fork 里已打） - 避免用
latest或main：Go modules 不解析这些词，也不保证可重现
replace 和 vendor、IDE 缓存的冲突点
即使 replace 配置正确，go build 成功，也可能出现 IDE 跳转不到本地代码、或者 go mod vendor 拉的还是远程包——这不是 replace 失效，而是工具链没刷新上下文。
立即学习“go语言免费学习笔记（深入）”；
- 启用
vendor时，go mod vendor默认只拉require列表里的原始路径，不会自动按 replace 替换；必须先go mod tidy，再go mod vendor - VS Code + gopls：改完
go.mod后需手动触发gopls restart或点击右下角 “Reload Window” - Goland：改完后点菜单
File → Reload project from disk，否则仍按旧 module graph 解析
