必须手动干预，go mod tidy 不会识别或删除 import v1 路径但模块含 v2+ 版本的不兼容残留；需通过 go list -m all、grep 源码、go mod graph 和 go mod why 定位并分步清理旧路径引用。
直接看 go list -m all 输出里哪些模块版本号带 v2 或更高主版本，但你的代码还在 import 它的 v1 路径——这种就是典型不兼容残留，必须手动干预，go mod tidy 不会帮你识别或删除它。
查清谁在用旧版 SDK 路径
新版 SDK 通常改用新导入路径（比如从 github.com/aws/aws-sdk-go 升级到 github.com/aws/aws-sdk-go-v2），但老代码可能还留着旧 import。光看 go.mod 里的 require 行容易漏掉：
- 运行
grep -r "import.*aws-sdk-go" ./ --include="*.go"，确认是否真有源码在引用旧路径 - 执行
go list -m all | grep aws-sdk-go，如果同时出现v1.45.0和v2.20.0，说明两者共存，但 Go 只能选一个——此时旧版大概率被间接拉入，且无法正常工作 -
go mod graph | grep aws-sdk-go能定位是哪个依赖包偷偷引入了旧版（常见于过时的中间件封装库）
清理前先验证旧版是否真被需要
别急着删。有些模块虽未显式 import，但通过反射、插件机制或测试专用逻辑加载，go mod tidy 会误判为“无用”：
- 运行
go mod why github.com/aws/aws-sdk-go，如果输出是(main module does not need module)，基本可删；如果显示一串调用链（如→ github.com/some/legacy-lib → github.com/aws/aws-sdk-go），就得先升级那个 legacy-lib - 检查是否有
//go:build integration或_test.go文件里 import 了旧 SDK——go mod tidy默认处理测试依赖，但你要确认这些测试是否还有效 - 执行
go build -tags=integration ./...看是否报错，避免删掉后 CI 构建失败
替换或移除旧 SDK 的正确顺序
硬删 require 行往往导致构建失败，因为下游依赖还没适配新版。稳妥做法是分步走：
- 先用
replace github.com/aws/aws-sdk-go => github.com/aws/aws-sdk-go-v2 v2.20.0试水——不行，路径不匹配，Go 不认；replace只能映射同名模块，不能跨路径重定向 - 正确做法：找到拉入旧版的上游模块，运行
go get upstream-module@latest，看它是否已支持 v2；若没支持，只能 fork 它并 patch import 路径，再用replace指向你的 fork - 确认所有 import 都切到新路径后，再执行
go mod tidy，旧版才会真正从go.mod和go.sum中消失 - 最后跑
go list -m all | grep aws-sdk-go，应只剩 v2 版本；再执行go mod verify确保校验和一致
容易被忽略的兼容性断裂点
SDK 主版本升级不只是路径变化，更常伴随方法签名、错误类型、配置结构体字段的破坏性变更：
- 即使编译通过，运行时可能 panic：比如旧版
sess.Config.Credentials在 v2 里变成config.Credentials，且类型不同 - JSON 序列化行为可能变：v2 默认开启 strict mode，对空字段处理更严格，老代码若依赖宽松解析会出问题
- 别只信文档——用
go list -json -exported -deps=false ./...抽出你代码里实际使用的导出符号，和新版 SDK 的做比对，才能发现隐藏的不兼容
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
