ambiguous import错误源于同一导入路径被多个模块声明不同版本，如github.com/ugorji/go v1.1.4与github.com/ugorji/go/codec v1.2.9冲突；需用go list和go mod graph定位，通过require统一版本、replace强制归一、go mod tidy清理。
为什么 go build 报错 “ambiguous import” 或 “duplicate symbol”？
根本原因不是 Go 本身不支持多版本共存，而是你项目里同时引入了两个模块路径相同但实际内容不同的副本——比如一个来自 github.com/foo/bar 的 v1.2.0 tag，另一个是同一仓库的 v1.2.0 分支（或未打 tag 的 commit），Go 模块系统会把它们视为不同模块，但编译器在链接时发现包路径重复，就直接拒绝。
常见诱因包括：
- 本地
replace指向了未 clean 的本地 fork，而go.mod里又保留了原远程依赖 - 某依赖项在
go.sum中记录了多个 checksum，对应不同 commit，但模块路径没变 - 用了
git submodule或手动拷贝源码到vendor/，又没关掉GO111MODULE=off或没加-mod=vendor
如何用 go mod graph 定位冲突源头？
go mod graph 输出的是“谁依赖了谁”，但它不会显示版本差异。真正有用的是配合 go list -m -f '{{.Path}} {{.Version}}' all，它能列出所有被解析出的实际模块路径和版本号。
执行后如果看到两行都含 github.com/sirupsen/logrus，但一行是 v1.9.0，另一行是 (devel) 或 v1.9.0-0.20230101123456-abcd123，说明有非标准版本混入。
立即学习“go语言免费学习笔记（深入）”；
进一步确认：运行 go mod why -m github.com/sirupsen/logrus，看哪个依赖项偷偷拉进了不一致的版本。
replace 和 exclude 到底该选哪个？
replace 是强制重定向模块路径，适合你确实要换实现（比如用 patch 版本），但它不能解决“两个不同 commit 被同时拉进来”的问题——因为 replace 后，原路径还在被其他依赖引用，冲突照旧。
exclude 才是治本之策：它告诉 Go，“这个版本我明确不要”，让模块解析器跳过它。例如：
exclude github.com/sirupsen/logrus v1.9.0-0.20230101123456-abcd123
注意：exclude 只对当前 module 生效，且必须写在 go.mod 顶层；它不阻止别人依赖它，只阻止你自己 resolve 到它。
实操建议：
- 先用
go list -m -f '{{.Path}} {{.Version}}' all | grep xxx找出所有异常版本 - 逐个
exclude掉非标准版本（带-0.或(devel)的） - 再
go mod tidy，观察是否还有残留
CI 环境下为什么本地能编译、CI 却失败？
因为 CI 往往清空 $GOPATH/pkg/mod，触发全新模块下载，而本地可能缓存了某个旧 commit 的 zip 包，恰好绕过了冲突校验。
关键检查点：
- CI 是否设置了
GO111MODULE=on？没设的话，go.mod可能被忽略 - CI 是否执行了
go mod download再build？没下载就 build，可能 fallback 到 GOPATH - CI 使用的 Go 版本是否 ≥ 1.18？1.17 及更早对
exclude支持不完整
最稳妥做法：CI 中显式加一步 go mod verify，它会校验 go.sum 和实际下载内容是否一致，提前暴露 checksum 不匹配问题。
模块依赖的标签冲突本质是“路径相同但语义不同”，Go 不做自动合并，也不允许模糊匹配——你得亲手告诉它哪个该留、哪个该踢。别指望 tidy 自动修，它只管拓扑，不管语义。
