replace语句必须写在go.mod文件的replace段中，且位于require块之后、exclude或retract之前；写错位置或误入go.sum会导致失效。
replace 语句写在哪？为什么 go.mod 里不生效
本地模块替换必须写在 go.mod 文件的 replace 段，且只能出现在 require 块之后、exclude 或 retract 之前。常见错误是把 replace 写在 require 上面，或误塞进 go.sum —— 那里只存校验和，写进去会被 go mod tidy 清掉。
-
replace必须指向一个含有效go.mod的目录（可以是相对路径，如./mylib，也可以是绝对路径） - 被替换的模块名（左边）必须与
require中声明的完全一致，包括版本号（如github.com/user/lib v1.2.0），哪怕你只想替换v1.2.0这个版本 - 如果目标模块还没打 tag，别用
latest或master—— Go 不认这些，得用=> ./local-path显式映射
go build 时 replace 不起作用？检查 GOPROXY 和 vendor 状态
即使 go.mod 写对了，go build 仍可能拉远端模块：因为 GOPROXY 默认开启，且 vendor 目录存在时会优先用它。这不是 bug，是 Go 的确定性依赖策略。
- 运行
go env GOPROXY，如果输出不是off或包含direct，就可能绕过replace—— 临时关掉：GOPROXY=off go build - 如果有
vendor/目录，go build -mod=readonly会拒绝读取replace；要么删掉vendor，要么加-mod=mod强制走 module 模式 - 执行
go mod graph | grep your-module-name，能直接看到当前解析出的实际依赖路径，比猜靠谱得多
测试时 import 路径没变，但实际加载的是本地代码？验证方法
替换成功后，import 路径不变（仍是 "github.com/user/lib"），但源码来自本地。光看编译不报错不够，得确认 runtime 行为真变了。
- 在本地模块里加一行
fmt.Println("loaded from local")，然后运行主程序 —— 输出出现才算真正生效 - 用
go list -m -f '{{.Dir}}' github.com/user/lib查看 Go 实际使用的模块根目录，结果应该是你的本地路径，而不是$GOPATH/pkg/mod/... - 如果模块有 init 函数或包级变量，改个值再构建，观察行为是否同步更新 —— 这比看日志更直接
发布前忘记清理 replace？CI 构建失败的典型原因
replace 是开发期临时手段，进 CI 或发布包时必须移除，否则别人 clone 你的代码根本跑不起来：他们的机器上没有你本地那个路径。
立即学习“go语言免费学习笔记（深入）”；
- CI 脚本里加一句
grep -q "replace" go.mod && echo "ERROR: replace found in go.mod" && exit 1，提前拦截 - 不要用
go mod edit -replace动态加 replace 后直接提交 —— 容易漏删；推荐用分支隔离：开发分支留replace，合并到 main 前手动删 - 如果必须保留某种“可切换”能力，改用
//go:build local+ 单独的main_local.go文件控制导入，而不是靠replace欺骗模块系统
replace 的边界很窄：它只影响当前 module 的构建视图，不改变 import 路径，也不传播给下游。这点一旦混淆，调试成本会陡增。
