go大版本升级需同步修改import路径为/v2等后缀，仅改go.mod版本号会导致编译报错；须用go list查可用版本，显式执行go get带后缀路径，再手动运行go mod tidy并验证go.sum。
大版本升级必须改 import 路径，否则编译直接报错
Go 模块对 v2+ 主版本有硬性路径要求：不能只改 go.mod 里的版本号，代码中所有 import 语句也必须同步加上 /v2（或对应后缀）。比如从 github.com/spf13/cobra 升到 v2，就得把所有 import "github.com/spf13/cobra" 改成 import "github.com/spf13/cobra/v2"。漏改任意一处，go build 就会提示 cannot load github.com/spf13/cobra/v2: module github.com/spf13/cobra/v2@latest found 这类错误——它不是没拉到，而是根本没被引用。
先查可用版本再动手，别依赖 @latest
go list -m -versions github.com/spf13/cobra 是安全起点，能列出该模块所有已发布 tag，确认 v2.0.0 或 v2.1.0 是否真实存在。用 @latest 很可能跳到一个未按规范发布的 v2 分支（比如路径仍是 /cobra 而非 /cobra/v2），导致 go get 拒绝安装并报 invalid version。正确做法是显式指定带后缀的路径和版本：go get github.com/spf13/cobra/v2@v2.1.0。
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
升级后 go mod tidy 不会自动补全，得手动触发
go mod tidy 的作用是收敛依赖树，不是升级工具。它不会主动把旧路径替换成新路径，也不会帮你补上因路径变更而缺失的间接依赖。执行完 go get github.com/spf13/cobra/v2@v2.1.0 后，必须立刻运行 go mod tidy，否则 go build 可能报找不到 github.com/spf13/cobra/v2 的模块定义。同时注意检查 go.sum 是否新增了对应条目，缺失意味着校验失败风险。
多个主版本共存？Go 不允许，但可隔离路径
同一个模块的 v1 和 v2 不能同时出现在 import 列表里，否则 go build 报 duplicate symbol 类错误。如果项目中部分代码还依赖旧版，唯一办法是彻底拆分：把用 v1 的逻辑移到子模块（新建 module example.com/myapp/legacy），并在其 go.mod 中单独 require github.com/spf13/cobra v1.8.0。主模块只保留 v2 路径。这种结构虽稍重，但比用 replace 硬顶更可控——后者会绕过 go.sum 校验，且影响整个模块树。
Breaking changes 条目，并在本地跑全量测试，而不是等 CI 失败才回头查。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
