go mod replace 是临时重定向模块路径的机制，仅在当前模块生效，用于灰度发布、本地调试或 fork 修复，不可提交至生产环境，上线前必须清理。
灰度发布依赖：用 replace 临时替换模块路径
灰度发布不是靠改 go.mod 里的版本号，而是让部分服务先用新代码跑起来，同时不破坏其他服务的稳定性。核心手段是 replace —— 它只影响当前模块的构建行为，不改变下游用户的导入路径。
常见错误是把 replace 当成“升级指令”写进 go.mod 后直接提交，结果导致 CI 构建失败或本地无法复现。它本质是开发期覆盖，不是发布策略。
- 想验证私有 fork 的修复：在
go.mod中加replace github.com/old/lib => ./fixes，本地跑通后删掉这行再提 PR - 想试用未打 tag 的分支：用
replace github.com/org/pkg => github.com/org/pkg v0.0.0-20260720123456-abcdef123456（伪版本），但别提交到主干 - 跨模块联调时，若 A 依赖 B，B 又依赖 C，而你想让 A 直接用本地修改的 C：必须在 A 的
go.mod里replaceC，不能只在 B 里改
大版本迭代：模块路径必须带 /v2 后缀
Go 不允许同一模块路径下存在不兼容变更。比如从 v1 升到 v2，不是改 require github.com/x/y v1.5.0 为 v2.0.0 就完事——那样会触发 MVS 算法降级或冲突，且下游无法同时引用 v1 和 v2。
真正合规的做法是：新版本模块路径必须含 /v2，例如 module github.com/x/y/v2，对应导入路径也变成 github.com/x/y/v2。否则 go get 会拒绝解析，报错 unknown revision 或 invalid version。
- 旧版还在维护？保留
github.com/x/y分支打 v1.x tag，新版走github.com/x/y/v2独立仓库或子目录 - 发布前必须打 Git tag：
v2.0.0（带v前缀），否则go list -m -versions github.com/x/y/v2查不到可用版本 - 下游升级时要手动改 import 路径，IDE 通常不自动处理，容易漏改导致编译失败
灰度期间如何共存 v1 和 v2 依赖
一个项目里同时引用同一库的 v1 和 v2 版本，是合法且常见的，比如迁移过程中老逻辑用 v1、新功能用 v2。Go 的模块系统天然支持这种“多版本共存”，前提是路径不同。
关键点在于：v1 和 v2 的模块路径必须严格区分，且不能通过 replace 强行指向同一路径，否则 go mod tidy 会报 ambiguous import。
- 确保 v1 模块路径是
github.com/x/y，v2 是github.com/x/y/v2，两者在go.mod中作为独立条目存在 - 不要在
go.mod里对 v2 做replace github.com/x/y/v2 => ./local-v2同时又保留 v1 的 require —— 这会让go list -m all显示重复路径 - 如果 v2 还没发布，可以用
go get github.com/x/y/v2@master拉取，但上线前必须切回正式 tag
CI 中验证灰度依赖是否被意外固化
go.sum 不该记录灰度期间用的本地路径或伪版本，否则会导致构建不可重现。CI 流水线必须能识别并拒绝这类污染。
最容易被忽略的是：开发者本地运行 go mod tidy 后提交了带 replace 的 go.mod 和对应校验和的 go.sum，CI 拉代码后直接 build，结果用了错误的依赖。
- CI 脚本开头加检查：
grep -q "replace" go.mod && echo "ERROR: replace found in go.mod" && exit 1 - 禁止在 CI 中执行
go mod download后再 commitgo.sum——go.sum应由开发者在 clean 环境下运行go mod tidy后提交 - 用
go list -m all | grep -E "(v[2-9]|/v[2-9])"扫描是否混入未经批准的大版本依赖
灰度的本质是控制范围，不是绕过规则。所有 replace 和临时版本都该在 merge 到主干前清理干净，否则下次升级时没人记得当初为什么那么写。
