必须先执行 go version 和 go env 确认当前基线：go version 显示版本及平台，go env GOROOT GOPATH GO111MODULE 用于判断模块模式（on/auto/off）及安装路径；GO111MODULE=off 且存在 go.mod 会导致 CI 构建失败；go.mod 中 go 指令影响编译行为，require 中 replace、indirect 和 v0.x 依赖在升级中易引发兼容性问题；建议用 go build -a -v 和 go test -vet=off ./... 暴露差异，并通过 go tool compile -S 对比汇编识别底层变化。
先跑 go version 和 go env 确认当前基线
不看版本号就动手升级，等于蒙眼修电路。必须先明确你当前在用什么：执行 go version 得到类似 go version go1.19.13 darwin/arm64 的输出；再跑 go env GOROOT GOPATH GO111MODULE，重点确认 GO111MODULE 是 on 还是 auto —— 如果是 off，说明项目还在 GOPATH 模式，升级路径完全不同。
常见错误现象：在 CI 流水线里看到 build failed: no required module provides package，往往就是 GO111MODULE=off 但项目已有 go.mod，导致构建行为不一致。
- Mac 用户注意：
GOROOT指向/usr/local/go时，大概率是手动安装；指向/opt/homebrew/Cellar/go/1.21.0则是 brew 安装，升级方式不同 - Windows 用户若
GOROOT是C:\Go，且 PATH 中有C:\Go\bin，说明走的是官方安装包路径 -
go list -m all | head -20可快速扫出依赖树头部，观察是否有大量v0.0.0-xxx或未打 tag 的 commit，这类依赖在新版 Go 下更容易暴露兼容性问题
查 go.mod 里的 go 行和 require 版本约束
go.mod 文件顶部的 go 1.x 行不是装饰，它是编译器行为开关。比如把 go 1.18 改成 go 1.22，go build 就会启用泛型类型推导增强、更严格的 nil 检查、以及 maps/slices 包的内置函数支持 —— 这些不会报错，但可能让旧代码逻辑悄然变化。
真正容易踩坑的是 require 部分：
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 存在
replace指向本地路径或 fork 分支？升级后go mod tidy可能忽略它，直接拉 upstream，导致行为回退 - 有
// indirect标记的依赖？它们没被显式 import，但新版 Go 的模块解析规则可能让其中某些被剔除，引发运行时 panic - 依赖中含
v0.x版本？Go 不承诺 v0 兼容性，go get -u升级时可能引入破坏性变更，比如返回值多一个 error
用 go build -a -v 和 go test -vet=off ./... 快速暴露底层差异
别只跑 go build 看是否成功。加 -a 强制重编所有依赖（包括标准库），能触发一些隐藏的链接期问题；加 -v 显示详细构建过程，方便定位卡在哪一个包。
go test 默认开启 vet 检查，但新版 Go 的 vet 规则更严。例如 Go 1.22 对 fmt.Printf 的参数类型匹配更严格，旧代码里 fmt.Printf("%s", myInt) 会直接报错。临时关掉 vet 能先验证逻辑是否通，再逐个修复：
- 先跑
go test -vet=off ./...，看测试是否全过 - 再跑
go test -vet=shadow,printf ./...（指定几个关键检查项），聚焦真正要修的问题 - 如果某测试在旧版 Go 里 panic 但在新版里静默跳过，可能是 runtime 行为变化，比如 GC 周期调整导致竞态窗口变窄
留意 go tool compile -S 输出的汇编差异
性能敏感服务升级后，不能只信 benchmark 数字。用 go tool compile -S main.go 对比新旧版本生成的汇编，能发现编译器优化带来的实际变化。比如 Go 1.22 启用 PGO 后，热点函数的内联深度可能增加，但某些边界 case 的分支预测反而变差。
这不是日常操作，但当你发现 QPS 下降 5% 且 profiling 没明显瓶颈时，值得花 10 分钟看下关键函数的汇编：
- 关注
CALL指令数量是否减少（内联效果） - 检查
MOVQ/LEAQ是否更紧凑（寄存器分配优化） - 注意是否有新增的
PCDATA或FUNCDATA段（调试信息膨胀，影响 cache line）
真正的麻烦往往不在语法或 API，而在编译器对内存布局、调度时机、逃逸分析的细微调整——这些不会报错，但会让线上行为变得难以复现。
