应执行 go mod tidy 自动合并重复 require 并选择最小可行版本，而非手动删除；若存在版本冲突，需通过 go mod graph 定位源头、检查 CHANGELOG 或使用 replace 临时锁定版本。
go.mod 中出现 require 重复或版本不一致怎么办
直接删掉重复的 require 行，保留语义版本号最高的那一行——但别急着手动改。Go 工具链会自动合并，手动编辑容易出错。执行 go mod tidy 后，Go 会重新解析所有依赖，只保留每个模块一个 require 条目，并选择满足所有间接依赖的最小可行版本。
常见错误现象：同一模块在 go.mod 中出现多次，比如：github.com/sirupsen/logrus v1.8.1github.com/sirupsen/logrus v1.9.0
这通常是因为不同依赖分别要求了不同版本，而 go mod tidy 还没运行，或被 // indirect 标记干扰。
- 运行前先确认当前目录是 module 根目录（有
go.mod文件） - 如果某依赖被标记为
// indirect却又在代码中直接 import，需先go get显式拉取，再tidy -
go mod graph | grep logrus可查谁在拉低版本，辅助定位冲突源头
升级某个依赖却导致其他包编译失败
这不是“升级失败”，而是新版本引入了不兼容的 API 变更（如函数签名改动、类型重命名），而你的代码或另一依赖仍按旧版调用。Go 的模块系统不会自动修复这类逻辑冲突，只保证版本可解析。
典型场景：把 golang.org/x/net 升到 v0.25.0 后，http2.Transport 字段名变了，而你项目里或某中间件硬编码访问了 .TLSClientConfig，但新版已改为 .TLSClientConfigFunc。
- 先用
go build -v看具体哪行报错，定位到调用方 - 检查该依赖的 CHANGELOG（通常在 GitHub Release 页面），确认 breaking change 清单
- 若无法立刻适配，可用
replace锁定旧版：replace golang.org/x/net => golang.org/x/net v0.18.0 - 注意：
replace只影响当前 module，不影响子 module；生产环境慎用，应尽快迁移
vendor 目录下包版本和 go.mod 不一致
go mod vendor 默认只复制 go.mod 解析出的最终版本，但如果你手动改过 vendor/ 里的文件、或之前用过 -mod=vendor 且未同步更新，就可能出现不一致。此时 go build 可能用 vendor，而 go list -m all 显示的是 go.mod 里的版本，造成困惑。
立即学习“go语言免费学习笔记（深入）”；
- 清理 vendor 并重建：
rm -rf vendor && go mod vendor - 验证一致性：
go list -m -f '{{.Path}} {{.Version}}' github.com/gorilla/mux
和grep -A 1 'github.com/gorilla/mux' vendor/modules.txt
输出应匹配 - CI 中建议禁用
vendor，直接用GO111MODULE=on go build，减少维护负担
多个子 module 共享同一依赖但版本不同
Go 不支持 workspace 级别的统一版本约束（类似 Rust 的 [workspace.dependencies]），每个 go.mod 独立解析。当你有 ./api/go.mod 和 ./cli/go.mod，它们各自 require zap v1.24.0 和 v1.26.0，顶层 go.mod 不会自动对齐。
解决思路不是强行统一，而是接受“局部最优”：只要各子 module 能独立构建、测试通过，版本差异本身不构成问题。真正要警惕的是跨 module 的接口传递——比如 ./api 导出一个带 zap.Logger 字段的 struct，而 ./cli 用不同版本 zap 构造它，会导致类型不兼容。
- 避免在公共 interface 或导出类型中暴露第三方类型
- 用
any或自定义 wrapper 封装日志器等易变依赖 - 若必须统一，可在顶层
go.mod中用replace强制所有子 module 使用指定版本（需确保各子 module 兼容）
go.mod，但 CI 拉取了新版本的 golang.org/x/tools，它又依赖新版 golang.org/x/mod，进而触发整个依赖树重算。这种“静默漂移”往往在两周后才暴露，建议在 go.mod 中固定关键工具链依赖，并定期 go list -u -m all 检查可升级项。 
