replace指令仅在当前模块的go.mod中生效，不影响下游模块；它优先于require版本，但需确保replace目标路径正确、go.mod声明一致且提交go.sum。
replace 指令只在当前模块的 go.mod 中生效
它不会影响依赖你的其他模块，也不会被下游模块自动继承。如果你在 go.mod 里写了 replace，那只对本项目 go build、go test 等命令起作用；别人 go get 你的模块时，看到的仍是原始依赖路径。
常见错误是以为加了 replace 就能“永久覆盖”某个依赖——结果 CI 构建失败，因为 CI 环境没读你的本地 go.mod（或者用了缓存的 module checksum），或者别人引用你模块时根本没加载这条规则。
- 必须提交修改后的
go.mod和go.sum（否则go mod tidy可能回滚或校验失败） -
replace后的路径如果是本地目录，必须是绝对路径或相对于当前go.mod的相对路径（推荐用相对路径，如./local/fork） - 如果 replace 目标是远程仓库（如
github.com/user/repo => github.com/myfork/repo v1.2.0），版本号不能省略，且该 commit 必须有对应 tag 或 pseudo-version
replace 与 require 版本冲突时以 replace 为准
Go 模块解析器会先按 require 拉取依赖，再用 replace 做运行时重定向。也就是说，即使 require 写的是 v1.0.0，只要 replace 指向了本地目录或另一个 commit，最终编译使用的就是 replace 后的内容。
但要注意：如果 replace 目标本身也有自己的 go.mod，且它的 require 里存在不兼容的版本（比如用了 Go 1.21 的语法，而你的主模块是 Go 1.19），构建会直接报错，而不是降级或忽略。
立即学习“go语言免费学习笔记（深入）”；
- 执行
go list -m all | grep xxx可确认实际加载的模块路径和版本 -
go mod graph能看出 replace 是否生效（被替换的模块名会出现两次：一次原始路径，一次 replace 后路径） - 若 replace 后出现
missing required module，大概率是 replace 目录下go.mod的 module path 与原路径不一致（比如少了/v2后缀）
replace 不能替代 fork + import path 修改
当你需要长期维护一个依赖的定制版，仅靠 replace 是脆弱的：它不改变 import path，所有源码仍写 "github.com/orig/repo"；一旦某天删掉 replace 行，代码立刻无法编译。真正可持续的做法是 fork 后改 module 名（如 github.com/yourname/repo/v2），再把代码里所有 import 都更新过去。
replace 更适合临时调试、验证 patch、绕过不可用的上游 tag，或在 PR 被合入前先行集成。
- 临时测试补丁：用
replace github.com/x/y => ./fix-y，改完后删掉这行并提 PR - 避免私有库域名问题：比如公司内网模块
git.internal/pkg => ../pkg，但上线前必须切回真实 URL - 不要在公共库的
go.mod中长期保留 replace，尤其当目标是未公开的本地路径
replace 到本地目录时，目录必须含有效 go.mod
Go 不会自动为 replace 目录生成 go.mod。如果只是拷贝源码到 ./vendor/foo 但没运行 go mod init，go build 会报 cannot load github.com/xxx: cannot find module providing package github.com/xxx。
而且，replace 目录里的 go.mod 的 module 声明必须与原 import path 完全一致（包括 v2+/v3+ 后缀），否则类型、函数签名会被视为不同包，导致 “defined in multiple packages” 类型错误。
- 正确做法：
cd ./local/fork && go mod init github.com/orig/repo（不是你自己的域名） - 如果原模块带
/v2，replace 目录的go.mod第一行也得是module github.com/orig/repo/v2 - 执行
go mod tidy后检查go.sum是否新增了 replace 目录的 checksum（没有说明没生效）
