先说几个关键点：go mod replace 没生效，十有八九是写错了地方——你把 replace 加到了被替换依赖自己的 go.mod 里，而不是当前模块的 go.mod。要知道，replace 只对声明它的模块及其下游生效，没法跨级“注入”。另一个常见坑是路径写错：replace github.com/foo/bar => ./local-bar 里的 ./local-bar 必须相对于当前 go.mod 所在目录，并且该目录下得有一个有效的 go.mod（哪怕只写一行 module local-bar 也行）。
go mod replace 为什么没生效
除了上面说的位置和路径问题，还有几件事容易踩坑：
- 执行
go mod edit -replace=old=new之后，一定要跑一遍go mod tidy，否则go.sum和构建缓存不会真正更新。 - 如果被替换的是间接依赖（即你的模块没有直接 import 它），得先用
go mod graph | grep确认它到底由谁引入，然后在顶层模块中做 replace。 - 注意：
replace不会影响go list -m all的输出顺序，但会改变go build实际加载的代码路径。
replace 指向本地路径 vs 远程版本的区别
当 replace 指向本地路径（比如 ./my-fork）时，Go 会直接读取该目录的源码，跳过版本解析和校验；如果指向远程版本（比如 github.com/user/repo v1.2.3），则仍然走 module proxy 流程，只是把原始路径映射过去。前者适合调试和打补丁，后者适合统一降级或切到某个稳定 tag。
- 本地路径替换后，修改
./my-fork里的代码不需要重新go mod tidy，go build会自动感知变更。 - 远程版本替换需要确保目标版本真实存在，否则
go build会报missing go.sum entry。 - 用
go mod download -json可以验证替换后 Go 是否真的拉取了预期模块版本。
replace 和 exclude、replace 同时存在时谁优先
exclude 只影响版本选择阶段，它让某个版本彻底不参与 semver 排序；而 replace 是在版本选定后做路径重映射。两者不冲突，但行为叠加时容易误判：比如 exclude github.com/x/y v1.0.0 + replace github.com/x/y => ./y-fix，最终效果是「所有未被 exclude 的版本都映射到 ./y-fix」。
replace无法绕过require中声明的主版本约束（如github.com/x/y v1.0.0），它只改路径，不改语义版本号。- 如果同时有多个
replace匹配同一模块，以go.mod中**最后出现的一条为准**。 go mod vendor会把replace后的实际代码（而非原始路径）拷入vendor/目录。
replace 在 CI 或多环境部署时的坑
本地 replace 指向 ./xxx 的路径，在 CI 机器上大概率不存在，导致 go build 失败。这不是 Go 的 bug，而是设计使然：replace 的本地路径是开发期便利机制，不是部署方案。
- CI 中应避免使用本地路径 replace；如需定制代码，提前推送到私有 Git 仓库并 replace 到对应 commit hash。
- 不同环境（dev/staging/prod）不应靠修改
go.mod切换 replace，推荐用go mod edit -replace在构建前动态生成临时go.mod。 replace不会出现在go list -m -json的Replace字段里，除非你显式调用go mod graph或检查go.mod原文。
实际项目里最麻烦的不是怎么写 replace，而是当多个 replace 嵌套作用于同一个间接依赖时，得一层层 go mod graph 追踪来源，再确认每级 replace 是否被正确继承。这种链路一旦出错，错误信息里几乎不提示哪条 replace 生效了——只能靠删减法验证。
