go list -m all 显示的版本不等于实际编译加载的版本，后者需以 go build 日志或 go tool trace 为准；replace 生效需满足 GO111MODULE=on、有 go.mod、无 vendor/ 干扰，且输出含 => 符号。
go list -m all 看不清版本？先确认你真在 module 模式下
很多“依赖冲突”根本不是冲突，而是 GO111MODULE 没开或项目没识别成模块。执行 go list -m，如果报错 go: not in a module，说明当前是 GOPATH 模式——go.mod 和 replace 全部失效，go.sum 也不会生成。
必须确保：go env GO111MODULE 输出 on；项目根目录有 go.mod 文件；且没有残留的 vendor/ 目录干扰（老项目迁移时容易漏删）。
- CI 脚本里务必显式写
export GO111MODULE=on，别信默认值 -
go mod init后立刻跑一次go mod tidy，别等编译失败才动手 - 看到
// indirect行别直接删——它可能是关键间接依赖，删了反而触发更隐蔽的版本回退
go mod graph 显示多个版本？用 go mod why 定位谁在偷偷拉旧版
go mod graph | grep some-module 常常爆出一堆路径和版本，但光看图没法判断哪条链真正影响构建。真正有用的是 go mod why -m github.com/some/pkg@v1.2.0 —— 它会输出从 main 包开始、一路 import 到该版本的完整调用链。
常见陷阱：
立即学习“go语言免费学习笔记（深入）”；
- 某个测试文件 import 了旧版工具包，导致整个模块被锁死在低版本
- 第三方库的
go.mod里写了过时的require，而你又没升级它本身 -
go list -m all显示的版本 ≠ 实际编译时加载的版本（后者以go build日志或go tool trace为准）
replace 不生效？检查它是否被更高优先级规则覆盖
replace 是最常用的干预手段，但极易失效。典型原因：
- 同一模块被多个
replace声明，Go 只取第一个，后面的被忽略 -
replace路径写错：比如github.com/a/b和github.com/a/b/v2是两个不同模块，不能互相替换 - 本地路径
./local-fix在 CI 构建时不存在，直接 panic - 上游模块已通过
require显式声明了版本，且该版本满足所有约束，replace就不会触发
验证是否生效：运行 go list -m all | grep some-pkg，输出里必须带 => 符号，例如 github.com/some/pkg v1.2.3 => ./local-fix。
go mod tidy 清不掉冲突？它只管“最小集合”，不管“你想要哪个”
go mod tidy 的作用是删除未引用的 require 行，并补全缺失的间接依赖——但它**不会主动降级或升级已有依赖**。如果你的 go.mod 里写着 require github.com/some/pkg v1.0.0，即使 v1.5.0 已发布且完全兼容，tidy 也绝不会帮你升。
真正要强制更新，得用：
-
go get github.com/some/pkg@latest（拉最新 tag） -
go get github.com/some/pkg@v1.5.0（指定版本） -
go get -u（升级所有可兼容的次要版本）
注意：go get -u 可能升级太多，建议配合 go list -m -u all 先看清单，再逐个 go get 控制节奏。
最后提醒一句：replace 不是补丁，是临时拐杖。上线前没推 PR 修复上游，就等于把技术债打包进生产环境。
