replace必须写在go.mod文件中且仅对当前模块生效，须置于require块之后、文件末尾，左侧路径须与import及require完全一致，右侧须为含合法go.mod的本地相对路径，module名大小写等细节必须严格匹配。
replace 必须写在 go.mod 里，且位置不能错
Go 的 replace 不是命令行参数，也不是构建时开关——它只在 go.mod 文件中生效，且必须放在 require 块之后、文件末尾。写在 require 里面、注释里、或者 go.sum 里，全都不起作用。
常见错误现象：go run main.go 还是用远程版本；go list -m all 不显示本地路径；VS Code 里跳转仍指向 GOPATH 或 proxy 下载的代码——大概率是 replace 写错位置或格式不合法。
-
replace github.com/user/lib => ./local/lib是合法写法；replace github.com/user/lib => /home/user/lib（绝对路径）虽能用，但 CI/CD 会炸，不推荐 - 右侧路径必须以
./开头（相对路径），不能是~/或空路径 - 如果本地模块在父目录，比如
../lib，确保该路径下确实存在go.mod，且当前项目能正确解析其 module 名
本地模块必须有合法的 go.mod，且 module 名要完全一致
replace 不是“复制粘贴”，而是路径重定向。Go 工具链会去目标路径读取 go.mod，并校验其中第一行 module 声明是否与 replace 左侧完全匹配（包括大小写、路径结构、甚至 v1 这样的子模块后缀）。
如果本地模块没 go.mod，go mod tidy 会报错：no required module provides package；如果 module 行写成 module github.com/User/lib（首字母大写），而 replace 写的是 github.com/user/lib，就会静默失效——Go 不做大小写归一化。
立即学习“go语言免费学习笔记（深入）”；
- 进到本地模块目录，运行
go mod init github.com/user/lib初始化（注意路径和 replace 左侧严格一致） - 本地模块可以没有
require，但不能是空文件；至少有一个可导出函数或go.mod被 Go 认为“有效” - 如果本地模块还没打 tag，Go 会生成伪版本（如
v0.0.0-20260804160300-abc123），这是正常行为，不影响调试
go mod tidy 后怎么确认 replace 生效了？别信 IDE
IDE 的依赖高亮经常缓存滞后，甚至误判。唯一可信的方式是让 Go 自己说：运行 go list -m all | grep your-module。如果看到类似 github.com/user/lib v0.0.0-00010101000000-000000000000 => ./local/lib 的输出，说明替换已生效。
- 执行
go mod tidy后，检查go.mod是否新增了replace行，且没报错 - 改一行本地模块里的日志或返回值，再
go run，观察输出是否同步更新 - 如果
go list显示的是远程版本号（如v1.2.3）而非=>指向本地路径，说明replace被忽略——回头检查 module 名、路径、go.mod 存在性三个硬条件
调试完必须手动清理 replace，否则上线就失败
replace 是开发期临时机制，不被下游继承，也不参与构建传播——但它会卡在你的 go.mod 里，直到你删掉。CI/CD 流水线没有你的 ./local/lib，构建必然失败；同事拉代码也会因路径不存在而 go mod tidy 报错。
不要依赖“注释掉”来临时禁用——Git diff 容易漏看，CI 也可能读取注释行。真正安全的做法是：调试结束立刻执行 go mod edit -dropreplace=github.com/user/lib，或者直接删掉那行。
- 团队协作时，可以用
//go:build ignore_replace+ 构建 tag 隔离，但不如彻底移除干净 - 如果多个模块都要替换，建议用 Go Workspaces（
go work init），比一堆replace更易维护 - 记住：Go 不会自动帮你回滚，也不会警告你“这个 replace 还在”，它只安静地按你写的跑——直到某天构建崩了
