replace 指令作用域限于当前 go.mod 文件，不会穿透多层嵌套模块；每个依赖模块需在自身 go.mod 中独立声明 replace，否则运行时可能因使用旧版依赖而 panic；上线前必须用 go mod edit -dropreplace 清理本地路径映射。
本地 replace 指令必须按路径层级逐层声明
多模块嵌套时，replace 不会自动穿透。比如 cmd/app 依赖 pkg/service，而 pkg/service 又依赖 pkg/util，你在 cmd/app/go.mod 里只写 replace pkg/service => ./../pkg/service，Go 仍会从远程拉取 pkg/util 的发布版本——除非你在 pkg/service/go.mod 里也加一条 replace pkg/util => ./../util。
常见错误现象：go build 成功但运行时 panic，报错类似 undefined: util.SomeFunc，实际是 pkg/service 编译时用了旧版 pkg/util，而你本地改了接口但没生效。
-
replace是 module 级作用域，每个 go.mod 文件需独立管理自己的依赖映射 - 路径必须相对于当前
go.mod文件位置，不是相对于项目根目录 - CI 流程中应校验所有子模块的
go.mod是否含replace，防止误提交
根目录 go.mod 不能替代子模块的 require 声明
有人试图在项目根目录 go.mod 中统一 require 所有子模块，再用 replace 指向本地路径，以为能“一键同步”。这行不通：Go 构建时只读取入口模块（如 cmd/app）的 go.mod，根目录的 go.mod 若未被直接构建，其 require 和 replace 完全不生效。
使用场景：你正在调试 cmd/app，它 import pkg/service；此时 Go 解析依赖链只看 cmd/app/go.mod → pkg/service/go.mod，根本不会加载根目录 go.mod。
- 每个可构建模块（含
main函数）必须有自己的go.mod，并显式声明所依赖的其他本地模块 - 根目录
go.mod仅在你执行go mod tidy于根目录时有用，用于统一检查或生成汇总视图 - 若想快速更新全部子模块的版本引用，需用脚本遍历各
go.mod执行go get -u=patch，而非依赖根目录控制
go mod edit -replace 要配合 -dropreplace 清理上线前残留
开发阶段频繁用 go mod edit -replace 切换本地路径，但上线打包前若忘记清理，会导致构建失败或引入不可控代码。Go 不允许在正式发布版本中保留 replace 指向相对路径（如 ./../pkg/util），因为该路径在 CI 环境或下游用户机器上不存在。
容易踩的坑：用 git commit -a 提交时漏掉某个子模块的 go.mod，导致部分 replace 残留；或者手动编辑 go.mod 时格式错位，触发 go mod verify 失败。
- 上线前必须运行
go mod edit -dropreplace=github.com/yourorg/pkg/util（替换为你的真实模块路径） - 推荐用 Makefile 封装：
make clean-replace自动清理所有replace行，再go get github.com/yourorg/pkg/util@v1.2.3补回正式版本 -
go mod graph | grep your-module可验证是否还有未清理的本地映射残留
v2+ 版本路径变更会彻底切断与 v1 的兼容性链
当某个嵌套模块升级到 v2（如 pkg/util 从 v1.5.0 升到 v2.0.0），且按规范修改模块路径为 github.com/yourorg/pkg/util/v2，那么所有依赖它的模块都必须同步改 import 路径和 require 条目。这不是“版本同步”问题，而是模块身份变更——Go 视为两个完全不同的模块。
性能影响：如果多个子模块分别依赖 util/v1 和 util/v2，它们会同时存在于构建图中，增加二进制体积和 go list -m all 输出长度，但不会冲突。
- 不要试图用
replace把v2路径映射回v1路径——Go 会拒绝解析，报错invalid version: unknown revision - 迁移必须双发：先发
v2tag 并更新所有require和import，再删掉旧v1分支（避免误引） - 若存在跨模块强耦合（如
service依赖util的具体 struct），升级 v2 前务必确认所有调用方已适配新 API，否则编译直接失败
replace 不穿透、go.mod 不越权、v2 不混用——这些边界一旦模糊，再多的 go mod tidy 也救不回版本漂移。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
