遇到“undefined: xxx”或类型不匹配报错，需定位第三方包版本变更点，核对changelog、更新import路径（含/v2）、检查依赖图并避免跨版本replace。
遇到 go build 报错 “undefined: xxx” 或 “cannot use yyy (type A) as type B” 怎么办
这八成是第三方包升级后改了函数签名、删了导出名，或重命名了类型。Go 没有运行时反射式兼容层，编译期直接卡死，没法“绕过去”。必须定位变更点，手动适配。
- 先用
git diff查看go.mod里该包的版本跳变（比如从v1.2.3升到v2.0.0），再查它的CHANGELOG.md或 GitHub Releases 页面 - 别信
go get -u—— 它可能把v1和v2混在一起拉，导致模块路径不一致（如github.com/foo/barvsgithub.com/foo/bar/v2） - 如果报错涉及类型不匹配，大概率是结构体字段被删/重命名，或方法返回值变了；用
go doc github.com/xxx/yyy对比旧版文档最直接
如何安全地升级一个带 /v2 路径的模块
Go 的语义化导入路径（/v2）不是可选功能，是强制隔离机制。升 v2 不是改个版本号就行，得同步改 import 路径和所有调用点。
- 先确认新版本是否真的用了
/v2：看它的go.mod文件里module行是不是以/v2结尾 - 执行
go get github.com/xxx/yyy/v2@latest，然后手动把代码里所有import "github.com/xxx/yyy"改成import yyyv2 "github.com/xxx/yyy/v2" - 注意别漏掉嵌套 import：有些包在
v2里把子包也挪了位置（比如github.com/xxx/yyy/config变成github.com/xxx/yyy/v2/config），这类路径要逐个 grep 核对
go mod tidy 后出现多个版本共存（require 里同时有 v1.5.0 和 v2.1.0）怎么办
这不是警告，是危险信号。说明项目里不同依赖间接引入了同一包的不同 major 版本，Go 会为它们分配不同导入路径，但你的代码可能无意中混用了两套 API，编译能过，运行时行为却不可控。
- 用
go list -m -u all | grep xxx查哪些依赖拉了老版本 - 用
go mod graph | grep xxx看谁在传递依赖里拖着旧版（输出格式是A B@v1.2.3，表示 A 依赖 B 的 v1.2.3） - 优先升级“上游依赖”：比如
pkgA依赖xxx/v1，而你又用了xxx/v2，那就得等pkgA发布支持 v2 的版本，或给它提 PR；临时方案是加replace，但仅限调试，不能进主干
为什么写了 replace 还是编译失败
replace 只影响当前 module 的构建，不影响依赖包内部的 import 路径解析。如果某个第三方包 A 的源码里硬写了 import "github.com/xxx/yyy"，而你用 replace 把它指向 v2 的本地路径，Go 会尝试把 v2 的代码按 v1 的路径去编译，必然炸。
立即学习“go语言免费学习笔记（深入）”；
-
replace只应在两种场景用：临时验证 patch、或彻底 fork 并重写所有 import（这时你要同步改它的go.mod和全部.go文件里的 import） - 检查
replace目标路径是否和原路径的 major 版本一致：替v1就用v1路径，替v2就用v2路径，跨版本 replace 是无效的 - 执行
go mod edit -replace=...后，务必跑一遍go mod tidy && go build ./...，光go build可能缓存旧状态
Breaking Change 的麻烦不在改代码，而在理清“谁在用谁、用的是哪一版、改了之后谁会崩”。花十分钟看清楚依赖图，比花两小时瞎试 replace 更省时间。
