模块路径映射重叠不是 go 的 bug，而是 import path 与物理路径不一致导致的解析歧义；唯一可靠解法是让每个仓库拥有独立、稳定、可解析的模块路径，并用 replace 在开发期临时绑定本地路径——但绝不提交到公共分支。
直接结论：模块路径映射重叠不是 Go 的 bug，而是 import path 与物理路径不一致导致的解析歧义；唯一可靠解法是让每个仓库拥有独立、稳定、可解析的模块路径，并用 replace 在开发期临时绑定本地路径——但绝不提交到公共分支。
为什么 go mod 会把不同仓库映射成同一个 import path
常见错误现象：go build 报 cannot find module providing package，或运行时加载了旧代码，实际却改了另一个仓库。根本原因是：两个仓库的 go.mod 文件里写了相同的 module 声明（比如都写 module github.com/yourorg/pkg），但它们实际托管在不同 Git 地址（如一个在 GitHub，一个在 GitLab 内网），或者其中一个还没推送到远端。
Go 不看 Git URL，只认 module 行声明的字符串。一旦多个物理仓库共享同一导入路径，go list -m all 就会混淆来源，go get 也只会拉取第一个匹配的远端地址——其余仓库的修改自然被忽略。
实操建议：
- 每个独立仓库必须有唯一
module路径，推荐格式为company.internal/repo-name或git.example.com/team/repo，避免复用github.com/xxx/yyy这类易迁移失联的路径 - 若已存在冲突，先停用所有
replace，执行go mod graph | grep conflicted-pkg定位哪几个模块在争抢同一路径 - 检查每个仓库根目录下的
go.mod是否含// +build ignore或残留注释（如 “legacy fork”），这些可能误导go mod tidy的依赖推导
用 replace 绑定本地路径时的三个硬性条件
很多人写完 replace github.com/old/pkg => ./local-pkg 就以为万事大吉，结果 go run 仍走远端版本。这不是配置没生效，而是没满足 Go 模块系统对 replace 的底层要求。
必须同时满足：
在 Go 中使用 google/wire 实现编译时依赖注入——wire.NewSet、wire.Build、wire.Bind（接口→实现）、wire.Struct、wire.Value、wire.Interface
-
./local-pkg目录下必须存在合法go.mod文件，且其module行与被替换的路径完全一致（大小写、斜杠方向都不能差） -
replace行必须放在当前项目go.mod的require块之后、文件末尾；若中间夹了exclude或其他指令，Go 会静默忽略该行 - 执行
go mod tidy后，要确认go.sum中新增了./local-pkg的校验和条目（形如github.com/old/pkg v0.0.0-00010101000000-000000000000 h1:...），否则说明 Go 没识别到本地模块
CI 构建失败：为什么本地能跑，CI 却报 replace 找不到路径
典型错误信息：replace github.com/yourorg/core => ../core: no matching versions for query "latest"。这不是版本问题，而是 CI 环境里 ../core 这个相对路径根本不存在——因为仓库是单独 clone 的，没有兄弟目录结构。
关键点在于：replace 是开发期 hack，不是构建方案。CI 必须还原为纯远端依赖：
- CI 流水线开头加一步：
sed -i '/^replace/d' go.mod && go mod tidy（Linux/macOS）或用 PowerShell 替换（Windows） - 确保所有被
replace的模块，已在远端打了对应 tag（如v1.2.3），且go.mod中require行版本号与之匹配 - 私有仓库必须提前配置
GOPRIVATE=*.internal,git.example.com，否则go mod tidy在 CI 中会因代理拦截而失败
模块路径改了，但旧项目还在用老 import，怎么办
比如把 github.com/olduser/pkg 迁到了 corp.internal/pkg，但下游几十个项目还没改代码。此时不能靠 replace 长期兜底，那只是掩盖问题。
可行做法只有两个：
- 在旧仓库（
github.com/olduser/pkg）根目录保留一个极简go.mod，内容仅一行：module corp.internal/pkg，并打新 tag（如v2.0.0）。这样go get github.com/olduser/pkg@v2.0.0会自动解析到新路径——前提是旧仓库 Git 地址仍可访问 - 若旧仓库已删，只能批量改下游代码：用
find . -name "*.go" -exec sed -i 's/github\.com\/olduser\/pkg/corp\.internal\/pkg/g' {} +，然后逐个验证go test是否通过；别忘了同步更新所有go.mod中的require行
最易被忽略的一点：模块路径变更后，sum.golang.org 不会自动同步新路径的 checksum。哪怕你打了一模一样的 tag 名，只要模块路径不同，就是全新模块，必须重新发布、重新校验。这点在灰度发布时尤其容易翻车。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
