17370845950

go get -u 默认仅升级到当前主版本内最新次版本，不会跨主版本升级；如需升至v2+须显式指定/v2路径，@latest取最新tag而非master分支。

go get -u 默认只升一级，不是最新版

很多人以为 go get -u 会把模块升级到最新稳定版，其实它只升级到「当前主版本内的最新次版本」。比如 github.com/sirupsen/logrus v1.9.3 已安装，运行 go get -u github.com/sirupsen/logrus 只会升到 v1.10.0（如果存在），但不会跨到 v2.0.0——因为 Go 模块语义化版本中 v2+ 被视为新模块，路径需含 /v2。

• 要强制升级到某具体版本，用 go get github.com/sirupsen/logrus@v1.10.0
• 想升到主版本最新（如 v2.x），必须显式指定路径：go get github.com/sirupsen/logrus/v2@latest
• @latest 不等于 @master：它取的是 tag 最新的 semver 版本，不包含未打 tag 的 commit

go list -m -u 显示可升级项但不自动更新

go list -m -u 是检查依赖是否过时的最轻量方式，但它只输出信息，不修改 go.mod。常见误操作是只看了输出就以为“已更新”，结果 go build 仍用旧版。

• 查所有可升级模块：go list -m -u all
• 查某模块是否可升级：go list -m -u github.com/gorilla/mux
• 输出中 [behind] 表示本地版本落后，[newest] 表示已是最新，[disallowed] 多因 replace 或 exclude 干预
• 真正升级仍需配合 go get 或手动改 go.mod 后 go mod tidy

  

go mod tidy 不会自动升级，只同步声明与实际使用

go mod tidy 常被误认为“升级工具”，其实它只做两件事：删掉没被引用的模块、补上缺失的间接依赖。即使远程有新版，只要代码没 import 新功能，tidy 就不会动版本号。

• 若你新增了 import "golang.org/x/exp/maps"，tidy 会拉取对应版本；但若只用了老版本的 maps.Clone，它不会主动切到带 maps.Copy 的新版
• 执行 tidy 前建议先 go get -u 或明确指定版本，否则容易卡在旧版
• CI 中慎用 go mod tidy -e（忽略错误）：可能掩盖因网络或权限导致的 module fetch 失败

升级后 test 失败？重点检查 breaking change 和 indirect 依赖

Go 模块升级最常出问题的地方不是语法报错，而是行为变更或间接依赖冲突。例如 golang.org/x/net 升级后 http2 的默认超时逻辑变化，或 google.golang.org/grpc v1.60+ 移除了 grpc.WithInsecure()。

• 查看 changelog 最快方式：go list -m -json github.com/hashicorp/go-version | jq -r '.Version' | xargs -I{} curl -s "https://api.github.com/repos/hashicorp/go-version/releases/tags/{}" | jq -r '.body'
• 检查 indirect 依赖是否被意外升级：go list -m -u -f '{{if .Indirect}} {{.Path}} {{.Version}} {{end}}' all
• 临时锁定某模块避免连锁升级：go mod edit -require=github.com/pmezard/go-difflib@v1.0.0 + go mod tidy

go mod graph | grep "golang.org/x/text" | head -5

这行命令能快速筛出哪些模块在拉取 golang.org/x/text，方便定位冲突源头。升级不是越新越好，尤其是 infra 类模块（如 x/net, x/sys），小版本也可能带来 syscall 行为差异。