Go 模块路径冲突导致 ambiguous import 的迁移

ambiguous import 不是普通的下载失败，而是 Go 在模块图中发现：同一个导入路径由两个模块同时提供，无法决定应该使用哪一份。模块拆分时，旧父模块仍保留原包，新子模块又开始提供同名包，最容易触发这个错误。

迁移的核心是让模块图只留下一个明确提供者：优先把父模块和拆分后的子模块配套升级；如果还在本地联调，可用 replace 指向本地代码，但它只是过渡定位手段，不能替代版本迁移。

Go 官方资料：https://go.dev/ref/mod

为什么会出现 ambiguous import

Go 的模块图把模块版本作为节点，导入路径再从这些节点中寻找包。当父模块 example.net/m 仍含有 example.net/m/p，而拆分后的 example.net/m/p 也单独发布时，同一个包路径就有两个候选来源。

# 下面是错误关系的静态示例，不是本次实际运行日志。
主模块 example.net/app
├── require example.net/m v0.1.0
│   └── 提供 example.net/m/p
└── require example.net/m/p v1.0.0
    └── 也提供 example.net/m/p

错误信息中的两个模块路径和目录位置，就是最有价值的线索。不要先清理模块缓存，也不要只改 import 字符串；先确认它们是否真的在模块图中同时出现。

先看模块图和主模块选择

排查时要同时看模块依赖和工作区选择。进入项目主模块目录后，使用以下命令查看模块列表、依赖边和当前 Go 读取的配置：

# 列出最终模块版本；重点找父模块和拆分子模块是否同时存在。
go list -m all

# 输出模块依赖边；它能帮助定位是谁把重复提供者带进来的。
go mod graph

# 查看主模块、工作区和额外参数，避免误读另一份 go.mod。
go env GOMOD GOWORK GOFLAGS

如果项目使用 go.work，工作区中的多个主模块和替换规则也会影响解析。可以用 GOWORK=off go list -m all 做单模块对照，但这只是定位差异，不代表所有项目都应该关闭工作区。

还可以针对冲突模块输出替换信息：

# 只查看目标模块的选择结果；示例路径需替换成项目真实模块。
go list -m -json example.net/m example.net/m/p

结果中的 Replace、版本和目录能区分三种情况：两个正式版本同时提供包、某个版本被本地目录替换，或者命令实际读取的主模块不是你以为的那一份。

迁移时要把父模块和子模块配套升级

如果拆分发布方提供了兼容的父模块版本，通常应让父模块先切换到已经移除旧包的版本，再选择拆分后的子模块版本。Go 官方测试样例也展示了“只升级子模块会冲突，同时升级父模块和子模块才能消除冲突”的边界。

# 同时指定父模块和拆分子模块，避免只升级其中一个。
go get example.net/m@v0.2.0 example.net/m/p@v1.0.0

# 重新整理直接和间接依赖；它不会替你选择错误的迁移策略。
go mod tidy

# 再观察最终模块图，确认重复提供者已经消失。
go list -m all

这里的版本只是教学占位符。真实迁移要以目标模块发布说明和项目兼容范围为准，不能把版本号机械替换成最新值。若父模块的新版已经把包移动到子模块，应用代码通常仍沿用原导入路径；只有在维护者明确改变 API 或导入路径时，才按迁移说明调整源码。

replace 能解决什么，不能解决什么

replace 适合本地联调、测试一个尚未发布的修复分支，或临时把某个模块版本指向本地目录。它改变的是模块内容的查找位置，不会自动从模块图中删除另一个同路径提供者。

// go.mod 示例：require 先把模块加入依赖图，replace 再把内容指向本地目录。
module example.net/app

go 1.23

require example.net/m/p v1.0.0

// 仅用于本地迁移过渡；发布前应决定是否改回可获取的版本。
replace example.net/m/p v1.0.0 => ../m-p

如果父模块仍然提供同一个包，单独增加这条 replace 仍可能冲突。正确顺序是先从 go list -m all 和 go mod graph 找到重复来源，再通过版本选择让提供者唯一；只有需要测试本地代码时，才加替换。

迁移完成后的兼容检查

发布库之前要特别注意：主模块里的 replace 不会自动成为使用者的替换策略。团队本地工作区可以保留过渡配置，但要在提交或发布前明确它是否应该删除；对外依赖应指向能够被正常获取的模块版本。

相关问题

只升级父模块还会冲突吗？

如果旧父模块版本仍包含同名包，而子模块也被间接引入，仍可能冲突。应查看最终模块图，不要只根据 go.mod 的直接 require 判断。

为什么改 import 路径不是首选修复？

模块拆分不一定意味着包的公开导入路径改变。先按维护者的迁移约定选择版本；只有官方明确要求新路径时，才修改源码中的 import。

go mod tidy 会自动消除 ambiguous import 吗？

不会。tidy 负责让 go.mod 与源码依赖保持一致，不能替你决定父模块和子模块哪一个应该拥有该包。

处理这类错误可以固定为三步：确认重复提供者，配套选择版本，最后再整理依赖。这样既能完成模块拆分迁移，也能避免用临时 replace 把冲突隐藏到下一次构建。