报错本质是依赖版本错位导致接口不兼容，需用go mod graph和go list验证冲突，再通过require+replace精准锁定版本，辅以exclude、patch升级或fork替换解决间接依赖漂移。
当你执行 go run 或 go build 时遇到 undefined: xxx 或 cannot load xxx: module xxx@latest found, but does not contain package xxx 这类报错，本质不是代码写错了，而是 go.mod 里某个依赖的版本被间接拉高或降级，导致接口签名不兼容、包路径变更或类型定义消失。
确认冲突是否真实存在
第一步不是改 go.mod，而是验证问题是否由依赖版本错位引发。
运行 go mod graph | grep 'xxx'（把 xxx 换成报错中提到的模块名，比如 github.com/redis/go-redis/v9），查看该模块在依赖树中实际被解析到哪个版本。如果输出多行、版本号不一致，说明存在冲突。
执行 go list -m all | grep 'xxx'，比对结果与 go.mod 中声明的版本是否一致。不一致就证明有上游模块强制覆盖了你的锁定。
【go.sum 文件不能删，否则下次 go mod download 会重新计算校验和，可能引入不同哈希的二进制】
精准锁定关键依赖版本
go-zero v1.9.2 明确要求 github.com/redis/go-redis/v9 ≥ v9.15.0，低于此版本会因上游回撤导致构建失败。这类强约束必须显式固定。
在 go.mod 文件末尾添加如下两行：
require github.com/redis/go-redis/v9 v9.15.0
replace github.com/redis/go-redis/v9 => github.com/redis/go-redis/v9 v9.15.0
replace 行确保即使其他模块 require 更高或更低版本，最终编译时也强制使用 v9.15.0。这是 go-zero 项目中最常踩的坑——只写 require 不加 replace，结果被 grpc-go 或其他中间件悄悄 downgrade。
执行 go mod tidy 后检查 go.mod 是否新增 indirect 标记。如果有，说明该版本未被当前代码直接 import，但被子依赖需要；此时 replace 仍有效，无需删除。
处理间接依赖版本漂移
方法一：用 exclude 彻底屏蔽危险版本
若某模块（如 github.com/golang/mock）的 v1.6.0 引入了不兼容的泛型语法，而你项目还在用 Go 1.19，可在 go.mod 中加入：
exclude github.com/golang/mock v1.6.0
这会让 go 命令跳过该版本，自动选择 v1.5.0 或 v1.6.1（如果存在且兼容）。
方法二：升级主干依赖链
运行 go get -u=patch github.com/zeromicro/go-zero，仅更新补丁级版本（如 v1.9.1 → v1.9.2），避免引入 breaking change。这个命令不会升级次版本号，适合线上项目紧急修复。
方法三：临时替换为 fork 分支
当某个依赖的官方版已放弃维护，但你又急需一个修复（例如 pgx 驱动对 PolarDB 的 SSL 元数据读取 bug），可执行：
go get github.com/yourname/pgx@fix-polarssl
再在 go.mod 中补上 replace 行指向你的 fork 地址。注意：fork 分支必须包含完整的 go.mod，且 module 名与原库一致，否则 import 路径会失效。
验证锁定是否生效
① 删除本地 pkg/mod 缓存目录中对应模块的全部版本（路径形如 $GOPATH/pkg/mod/cache/download/github.com/zeromicro/go-zero/@v/）。
② 执行 go mod download -x，观察日志中下载的确实是 v9.15.0 而非 v9.14.0 或 v9.16.0。
③ 运行 go build -o testbin ./...，确认不再出现 symbol lookup error 或 missing method 错误。
