replace必须写在当前项目go.mod文件中且仅对该模块生效，常见错误是误写入被替换依赖的go.mod或试图用命令行覆盖；本地路径替换需同时满足路径正确、本地有go.mod且module名完全一致三个条件，否则静默失效。
go mod replace 不是符号替换或路径伪装，它是在模块解析阶段做路径重映射——写错位置、路径不匹配、没执行 go mod tidy，都会让它完全静默失效。
replace 写在哪儿才真正起作用
它必须出现在当前项目的 go.mod 文件里，且只对这个模块生效。常见错误是把它加到被替换依赖自己的 go.mod 中，比如你想替换 github.com/foo/bar，却跑去编辑 ./vendor/github.com/foo/bar/go.mod —— 这毫无意义，Go 工具链根本不会读那里。
另一个高频误操作：以为能用命令行绕过，比如 go build -mod=replace=... 或设置 GOFLAGS。Go 模块系统不支持运行时覆盖，replace 是静态声明，不是开关。
- replace 必须写在当前项目根目录下的
go.mod中 - 可以放在
require块之前或之后，但不能嵌套在require里面 - 同一旧路径只认
go.mod中**最后出现的一条**replace
本地路径替换为什么总失败
最常卡在三个硬性条件没同时满足：路径算错、本地没 go.mod、module 名不一致。Go 不会报错提示，而是直接忽略该行 replace，退回到原始远程依赖。
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
例如你写 replace github.com/myorg/lib => ./local/lib，那 ./local/lib 目录下必须存在 go.mod，且第一行必须是 module github.com/myorg/lib —— 少一个字母、多一个斜杠、大小写不对，全都不生效。
- 右边路径必须是相对路径（以
./开头），不能是../或绝对路径（除非你明确需要且路径可访问） -
./local/lib下的go.mod必须存在，且module行与replace左边完全一致 - 本地模块不能是空壳：至少得有
go mod init，并导出至少一个包（哪怕只是package lib）
replace 指向远程 vs 本地的区别
指向本地路径（如 ./my-fix）时，Go 直接读源码，跳过版本校验和 proxy；指向远程版本（如 github.com/myfork/repo v1.2.3）则仍走 module proxy 流程，只是把原始路径映射过去。
前者适合打补丁、调试；后者适合统一降级或切稳定 tag。但注意：远程替换的目标版本必须真实存在，否则 go build 会报 missing go.sum entry。
- 本地替换后改代码，
go build会自动感知，无需重新go mod tidy - 远程替换需确保目标 commit/tag 在对应仓库存在，且
go mod download -json能查到它 -
go list -m all显示的是逻辑依赖树，不反映实际加载路径；可信的是go build -x输出里的cd /path/to/xxx行
CI 和多环境部署时 replace 的坑
本地 replace github.com/x/y => ./local-y 在 CI 机器上几乎必然失败——因为 ./local-y 根本不存在。这不是 bug，而是设计使然：replace 的本地路径机制只用于开发期验证，不是部署方案。
如果你发现某个 replace 在本地好用、CI 报错，第一反应不该是“怎么让 CI 找到路径”，而是“这个替换是否真有必要保留到生产”。
- 上线前务必移除所有指向
./xxx的replace，改用正式发布的 tag 或内部私有 proxy - CI 环境应禁用本地路径替换，可通过
go mod edit -dropreplace=...清理，或用go work隔离开发态 - 多个
replace同时存在时，优先级由go.mod中顺序决定，最后一条覆盖前面的
