go.mod 中 replace 指令失效主因是模块路径不匹配，需与 import 路径完全一致（含大小写、版本后缀）；新版模块变更常致编译失败或 runtime panic，应通过 go doc、go list -f '{{.Exports}}' 等工具定位差异，并优先使用 errors.Is() 和错误链机制处理 error 兼容性问题。
go.mod 中 replace 指令为什么没生效
常见现象是执行 go build 或 go test 后，旧包依然被加载，replace 像被忽略了一样。根本原因通常是模块路径不匹配：你写的 replace github.com/old/lib => ./local-fork 中的左边路径，必须和项目里 import 语句中实际引用的路径完全一致（包括大小写、版本后缀）。比如代码里写了 import "github.com/old/lib/v2"，但 replace 只写了 github.com/old/lib，那 v2 就不会被替换。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 用
go list -m all | grep old/lib查看当前解析出的实际模块路径和版本 -
replace行必须覆盖所有变体，例如同时写replace github.com/old/lib => ./new-impl和replace github.com/old/lib/v2 => ./new-impl - 如果依赖链中某中间模块硬编码了旧路径（如它自己的
go.mod里写了require github.com/old/lib v1.2.0），仅靠顶层replace不够，得配合go mod edit -replace批量注入
升级后出现 “undefined: xxx” 或类型不兼容
新版模块往往重构了导出符号：函数重命名、结构体字段删减、接口方法增减。Go 不做运行时兼容检查，编译失败是第一信号。重点不是“怎么修”，而是“怎么快速定位变更点”。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 先跑
go doc github.com/new/lib对比旧版文档，重点关注Changes或Migrating章节 - 用
go list -f '{{.Exports}}' github.com/new/lib查看新模块导出的符号列表，和旧版做 diff - 若新版用泛型重写了核心函数（如
Map[T, U]替代StringMap/IntMap），调用处需显式传入类型参数，不能省略 - 注意
context.Context参数是否被前置——很多 v2+ 版本把ctx从末尾移到第一个参数位，这是常见断点
vendor 目录里旧依赖残留导致构建不一致
即使 go.mod 已清理干净，vendor/ 里可能还躺着旧版 .a 文件或源码，go build -mod=vendor 会优先读它，结果本地能过 CI 却失败。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 删 vendor 前先确认
GOFLAGS="-mod=readonly"没被设为全局，否则go mod vendor会静默失败 - 执行
go mod vendor && git status vendor/，检查是否真清掉了旧路径；特别留意vendor/modules.txt是否仍含旧模块行 - CI 脚本里别只写
go build，显式加go mod tidy -v和go mod verify双保险 - 如果团队混用 vendor 和非 vendor 构建，建议统一禁用：
go env -w GOFLAGS="-mod=mod"，避免歧义
测试通过但 runtime panic：interface{} 转换失败
典型场景是新版模块返回的 error 类型变了——原来返回 *json.SyntaxError，新版改成了自定义 JSONParseError，而你的代码还用 errors.As(err, &json.SyntaxError{}) 强转，必然失败。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 别依赖具体 error 类型做判断，优先用
errors.Is()匹配已知错误值，或用errors.As()接口而非具体 struct - 新版模块若实现了
Unwrap()，可利用错误链机制，而不是硬拆底层类型 - 对第三方 error 类型做转换前，先查它的文档是否声明了 “compatible with
json.Unmarshaler” 这类契约；没有就视为不保证兼容 - 在关键路径加日志：打印
fmt.Printf("err type: %T, err: %+v", err, err)，比猜快得多
迁移本质是信任链重建：你信的不再是旧模块的 ABI，而是新版文档里白纸黑字写的契约。任何没写进文档的兼容性，都不该被当作事实依赖。
