go get -u 不升级到最新版，仅在当前主版本约束下升至最高兼容次/修订版本（如 v1.8.0 → v1.9.3），不跨 v1→v2；升最新稳定版需用 go get pkg@latest，且 v2+ 必须改 import 路径为 /v2。
go get -u 不等于“升到最新”，它只升兼容小版本
很多人执行 go get -u 后发现依赖没变，或者只升了一点点，不是 bug，是设计使然。go get -u 的逻辑是：在当前 require 的主版本约束下（比如 v1.8.0），找满足语义化版本规则的**最高次/修订版本**，但绝不会跨 v1 → v2。如果模块已声明 github.com/pkg/foo v1.5.0，它最多升到 v1.9.3，哪怕 v2.0.0 已发布。
真正想升到最新稳定版，得显式指定：go get github.com/pkg/foo@latest。但注意：@latest 取的是远程模块代理返回的最高 semver stable 版（如 v1.10.0 > v1.9.9），不包含 pre-release，也不等于 @master。
- 若你代码里 import 的是
github.com/pkg/foo，而@latest是v2.0.0，命令会失败——因为 Go 要求 v2+ 必须改 import 路径为github.com/pkg/foo/v2 - 升级后务必运行
go mod tidy，否则go.sum可能残留旧哈希，CI 构建时校验失败 -
go get -u ./会扫描子目录所有包并尝试升级其间接依赖，容易误触不稳定模块，生产环境慎用
先看谁在拉旧版本：用 go mod graph 和 go list -m -u 定位源头
升级失败或版本卡住，往往不是你想升的那个模块本身有问题，而是别的依赖把它“钉”在了旧版。比如 A 依赖 golang.org/x/net v0.17.0，B 依赖 v0.18.0，Go 的最小版本选择（MVS）算法会选 v0.18.0；但如果 C 强制 require v0.15.0，整个树就只能退到 v0.15.0。
查清谁在拖后腿：go mod graph | grep x/net 能列出所有引入该模块的路径；go list -m -u golang.org/x/net 显示当前版本和可升目标；go mod why golang.org/x/net 直接告诉你“为什么这个模块被拉进来”。
- 输出带
[behind]表示可升但没升，大概率是其他依赖锁死了版本 - 如果某模块显示
[disallowed]，检查go.mod里有没有replace或exclude干预了它 -
go list -m -u all耗时长，CI 中建议只对关键依赖做精准扫描
主版本升级必须改 import 路径，否则编译直接报错
Go 对 v2+ 的处理很硬：模块路径必须含 /v2（或 /v3 等），否则工具链不认它是新版本。所以从 v1 升 v2 不是改 go.mod 一行版本号的事，而是三步联动：
- 把所有
import "github.com/user/lib"改成import "github.com/user/lib/v2" - 更新
go.mod中的require行：从github.com/user/lib v1.9.0改为github.com/user/lib/v2 v2.0.0 - 跑
go build和go test ./—— v2 很可能删了旧方法、改了函数签名，光靠go mod tidy解决不了
别指望 replace 绕过路径变更。写 replace github.com/user/lib => github.com/user/lib/v2 v2.0.0 没用，Go 会忽略，因为它不匹配 import 路径。
测试失败时，重点盯 indirect 依赖和行为变更
升级后编译通过但运行异常，问题常藏在 indirect 依赖或 API 行为变化里。比如 golang.org/x/net 升级后，http2 的默认超时从 30s 缩短为 5s；google.golang.org/grpc v1.60+ 移除了 grpc.WithInsecure()，必须显式配 TLS 选项。
这类问题不会报语法错误，但会导致连接超时、认证失败等静默故障。
- 查
go.mod里带// indirect标记的模块——它们没被你直接 import，但被其他依赖拉进来，升级后行为可能突变 - 翻对应模块的 CHANGELOG.md 或 release note，尤其关注 “Breaking Changes” 和 “Behavior Changes” 小节
- CI 中不要只跑
go test，加一层集成测试（比如真实 HTTP 请求、DB 连接池压测），才能暴露底层依赖的行为漂移
真正的向下兼容不是靠工具自动保证的，是你对每个主版本变更做适配决策后的结果。路径改了、API 删了、默认值变了——这些都得人来判断、改代码、补测试。工具只负责把版本拉下来，不负责让逻辑继续跑通。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
