replace必须写在当前模块的go.mod中才生效，不是被替换模块自己的go.mod，也不是命令行参数或环境变量能控制的；go run或go build加任何flag都不会触发替换，go模块系统只认当前项目根目录下go.mod里的replace声明，且仅对本模块生效。
replace 必须写在当前模块的 go.mod 里才生效
不是被替换模块自己的 go.mod，也不是命令行参数或环境变量能控制的——go run 或 go build 加任何 flag 都不会触发替换。Go 模块系统只认当前项目根目录下 go.mod 文件里的 replace 声明，且仅对本模块及其构建过程生效。
常见错误是把 replace 写进被依赖库的 go.mod，结果主项目完全无感知；或者以为 GOFLAGS="-mod=replace" 能起作用，实际静默忽略。
-
replace行可以放在require块前或后，顺序不影响功能 - 同一旧路径只认第一个声明，后面重复的会被跳过
- 如果想覆盖间接依赖（比如 A → B → C，你想换 C），必须在顶层项目（A）的
go.mod中写replace
本地路径替换的三个硬性条件缺一不可
写了 replace github.com/user/lib => ./lib 却还是拉远程？大概率卡在这三点：
- 左边路径（
github.com/user/lib）必须和require行、代码中import的路径**完全一致**：大小写、末尾斜杠、版本后缀（如@v1.2.0）都不能差 - 右边路径（
./lib）必须是相对于当前go.mod所在目录的合法相对路径，且该目录下必须有go.mod文件 -
./lib/go.mod第一行的module声明必须和左边路径完全一致（例如module github.com/user/lib）
任意一条不满足，go mod tidy 不报错，但 replace 彻底失效，Go 会安静地回退到原始依赖。
调试时怎么确认 replace 真生效了
别信 IDE 高亮或 go list -m all 的排序，它只显示模块树结构，不反映实际加载路径。真正可信的是：
- 运行
go list -m -f '{{.Dir}}' github.com/user/lib，输出应为本地路径（如/your/project/lib），而非$GOPATH/pkg/mod/... - 修改
./lib里的代码，再go build，看行为是否同步变更（比如加个panic("hit local")是否触发） -
go mod graph | grep github.com/user/lib可确认它是否被当前模块直接引用，避免误判间接依赖链
注意：go mod vendor 会把 replace 后的真实代码拷进去，但 vendor 目录本身不能解决 import 路径错误——路径仍得严格匹配 module 声明。
上线前必须清理，CI 环境根本跑不通本地路径
replace github.com/user/lib => ../lib 这种写法在你本地开发很顺，但在 CI 机器上 ../lib 极大概率不存在，go build 直接失败。这不是 bug，是设计使然：本地路径替换纯属开发期便利机制。
上线前务必删掉或注释掉 replace 行；如果真要固化某个 fork 版本，改用远程替换：replace github.com/user/lib => github.com/you/lib v0.1.0-20260803123456-abc123，并确保该 commit 存在且含有效 go.mod。
跨团队协作时，建议用 .gitignore 过滤临时 replace 修改，或通过 Go Workspaces（go work use ./lib）隔离调试状态，避免污染主 go.mod。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
