replace语句必须写在go.mod文件中，且仅对当前模块生效；它不是命令行指令或构建参数，必须以replace old/path => new/path格式单行声明，新路径须为有效相对路径（如../lib）并含匹配module名的go.mod。
replace 语句写在哪？必须在 go.mod 里
replace 不是命令，也不是 build tag，它只在 go.mod 文件中生效。放在其他地方（比如 main.go 或注释里）完全无效。
常见错误是把 replace 当成临时调试开关，在 shell 里执行类似 go replace ... 的命令——Go 没这个命令。所有路径重定向都得靠 go.mod 里的声明。
- 必须在
module声明之后、require之前或之后（顺序不影响语义，但建议放 require 下方） - 每条 replace 单独一行，格式严格：
replace github.com/foo/bar => ../bar - 如果原模块带版本（如
github.com/foo/bar@v1.2.0），replace 也能匹配；不带版本则匹配该路径下所有版本 - 执行
go mod tidy后，replace 不会被自动删除——但若你删掉了本地目录或目标路径不可达，tidy 会报错并拒绝写入
本地路径替换时，相对路径比绝对路径更安全
用 ../somelib 而不是 /home/user/go/src/somelib，否则协作时别人 clone 项目后直接 go build 就会失败：路径不存在。
相对路径以当前 go.mod 所在目录为基准。假设项目结构如下：
立即学习“go语言免费学习笔记（深入）”；
myproject/
├── go.mod
└── cmd/
└── main.go
libs/
└── somelib/
├── go.mod
└── somelib.go
那么应在 myproject/go.mod 中写：
replace github.com/yourname/somelib => ../libs/somelib
- 目标目录必须包含合法的
go.mod文件，否则 Go 会报no matching versions for query "latest" - 不要用
./开头的路径（如./libs/somelib），Go 解析时可能出错；一律用../或更深层级的相对路径 - Windows 用户注意斜杠方向：Go 支持正斜杠
/，不用转义成反斜杠\
replace 不能解决跨主版本冲突，但能绕过版本约束
比如你同时依赖 gopay@v1.0.0 和 gopay@v1.5.0，Go Modules 默认只保留 v1.5.0——这不是 replace 能改的。replace 只改变“路径映射”，不改变语义化版本解析规则。
真正有效的做法是：用 replace 把两个不同版本指向两个**物理隔离的本地目录**，例如：
replace github.com/gopay/gopay@v1.0.0 => ../gopay-v1.0.0 replace github.com/gopay/gopay@v1.5.0 => ../gopay-v1.5.0
- 每个本地目录必须有自己独立的
go.mod，且 module 名需与原路径一致（如github.com/gopay/gopay） - 这种用法本质是“伪造多个模块实例”，适用于调试多版本兼容性，但上线前必须移除
- 如果只是想统一版本，优先用
require显式声明一个版本，再加replace指向本地实现，而非试图共存
发布前必须清理 replace，否则 CI 构建会失败
CI 环境通常没有你的本地目录结构，replace github.com/x/y => ../local/y 会导致 go build 直接报错：cannot find module providing package。
最容易被忽略的是：replace 不会出现在 go.sum 里，但它会影响整个依赖图的解析结果——这意味着即使本地能跑通，别人拉代码后第一次 go mod download 就卡住。
- 上线前检查：
git grep replace go.mod，确认无残留 - 不要依赖 “反正我本地没问题” —— replace 是开发期临时手段，不是部署方案
- 若需长期使用私有 fork，应发布到内部代理仓库（如 JFrog Artifactory），然后用
replace github.com/x/y => private.example.com/x/y v1.2.3
