panic提示interface conversion或method not found是运行时错误，源于分支版本方法签名变更、接口字段删除或struct导出状态不一致，因Go编译期仅检查当前模块导入版本，无法捕获跨版本不兼容问题。
运行时 panic 提示 interface conversion 或 method not found
这类错误不是编译失败，而是程序跑起来后才炸——说明你用的分支版本里某个方法签名变了、接口字段删了，或者 struct 字段导出状态不同。Go 不会在编译期报错，因为类型检查只看当前模块 import 的版本，而分支版本可能和依赖它的其他模块预期不一致。
常见诱因：go get github.com/some/pkg@main 或 @dev 拉了未发版代码，但该分支没经过下游模块测试；或者 replace 指向本地修改，却忘了同步上游关键 fix。
- 先确认 panic 点实际加载的是哪个版本：运行
go list -m all | grep some/pkg，看输出是否真为main或你指定的 commit hash - 再查这个版本被谁拉进来：
go mod why -m github.com/some/pkg，确认是不是你主动引入的，还是被某个间接依赖带进来的 - 如果确实是自己加的
replace或go get @main，立刻切回稳定 tag：比如go get github.com/some/pkg@v1.5.3，然后go mod tidy
go.mod 里有 replace 但 go list -m all 显示旧版本
replace 没生效，最常见原因是路径写错了——比如把 github.com/owner/repo 写成 github.com/owner/repo/v2，或者大小写不一致（Go 对模块路径大小写敏感）。
另一个隐蔽坑：你执行了 go get，但没加 -u，导致 go.mod 里的 require 行没更新，replace 就成了摆设。
立即学习“go语言免费学习笔记（深入）”；
- 检查
go.mod中replace行格式是否严格匹配：replace github.com/xxx/yyy => github.com/xxx/yyy v0.0.0-20230101000000-abcdef123456 - 运行
go mod edit -replace=github.com/xxx/yyy=github.com/xxx/yyy@v0.0.0-20230101000000-abcdef123456替代手写，避免格式错误 - 执行后立刻验证：
go list -m github.com/xxx/yyy应返回你指定的 commit，而不是v1.2.3这类 tag
vendor 目录里混着 main 分支代码和正式版本
当你用 go mod vendor 生成 vendor 时，它会按 go.mod 里最终解析出的版本复制文件。但如果 replace 指向本地路径（如 ./local-fix），vendor 会把那个本地目录整个拷进去——而 CI 构建时没这个路径，直接失败。
更麻烦的是：同一包在 vendor 里出现两份（一份是 tag 版本，一份是 main 分支），构建器可能随机 pick 一个，导致本地能跑、CI 报错。
- 禁止在主干分支提交含本地路径的
replace，CI 环境根本没法 resolve - 想保留调试用的本地 patch？改用 commit hash 替代：
replace github.com/xxx/yyy => github.com/xxx/yyy v0.0.0-20230101000000-abcdef123456 - 每次
go mod vendor后，手动检查vendor/github.com/xxx/yyy/下的go.mod文件内容，确认其module行和require行与你预期一致
go mod verify 报错 checksum mismatch
这说明你拉的分支版本在 proxy 缓存里没存校验和，或者你本地改过代码但没更新 go.sum。Go 会拒绝加载，但有时 panic 发生前已缓存了脏数据，导致行为不一致。
典型现象：本地 go run 成功，go build -o app 失败，或反之。
- 先清理缓存：
go clean -modcache，再重新go mod download - 强制刷新校验和：
go mod download -json github.com/xxx/yyy@v0.0.0-20230101000000-abcdef123456，观察输出是否包含"error" - 若仍失败，说明该 commit 未被官方 proxy 收录，必须用
GOPROXY=direct绕过代理，但仅限调试，上线前务必换回稳定 tag
