答案是go.mod声明版本与本地Go版本不匹配。常见现象为go build报“requires go X.Y or later”，实则因go.mod首行go X.Y高于或低于当前go version输出，需同步更新go.mod并运行go mod tidy检查incompatible提示。
go build 报错 requires go X.Y or later，但本地 go version 显示新版
这通常不是 Go 二进制没升级，而是项目 go.mod 文件里声明的 go X.Y 版本低于当前安装版本，或者——更危险的情况——高于当前版本。比如 go.mod 写着 go 1.26，而你只装了 go 1.25，go build 会直接拒绝执行，连错误堆栈都不给。
实操建议：
- 先运行
go version确认真实版本（别只看$GOROOT路径） - 检查
go.mod第一行go X.Y是否与go version输出一致；若刚升级到go 1.25，就把go.mod改成go 1.25 - 改完立刻执行
go mod tidy，它会重新解析依赖——注意控制台是否出现incompatible提示，那是 MVS 算法发现版本不兼容的信号
依赖包在新 Go 版本下 panic(nil)，旧版却没事
Go 1.22+ 对 panic(nil) 行为做了严格化：以前静默忽略，现在直接崩溃。这不是 bug，是语言收敛。常见于 panic(err) 且 err 为 nil 的场景，或调用 http.Error 时传入 nil 的 http.ResponseWriter。
实操建议：
- 全局搜索
panic(，重点检查括号内变量是否可能为nil - 留意标准库中易被忽略的 nil 参数点，如
json.Unmarshal(nil, &v)在 1.23+ 会 panic - 老库如
gopkg.in/yaml.v2在 Go 1.23+ 已知触发反射 panic，必须替换为gopkg.in/yaml.v3或github.com/go-yaml/yaml
//go:build go1.21 不生效，编译仍报函数未定义
//go:build 约束只有在文件顶部、紧贴 package 声明前且中间无空行时才生效。漏掉空行、加了注释、或放错位置，整个约束就失效——你写的 //go:build go1.21 实际上没起作用。
实操建议：
- 确保
//go:build行正上方**没有任何字符**（包括空格、tab、空行），且紧邻package行 - 多条件用空格分隔，例如
//go:build go1.21 && !windows是错的，应写成//go:build go1.21 !windows - 用
!go1.20匹配的是所有 **低于** 1.20 的版本，不包含 1.20 本身——这点极易误判 - 为兼容老工具链，可同时保留
// +build注释，但以//go:build为准
go build ./ 仍链接旧版 .a 文件，修改依赖后符号未定义
Go 不会自动重编译已缓存的依赖包。如果你用 go install server 编译过 server 包，它会被缓存为 $GOPATH/pkg/linux_amd64/server.a；后续 go build main.go 会直接复用这个旧版归档，导致你改了 server/server.go 却看不到效果，甚至报 undefined: foo.MyName。
实操建议：
- 永远不要单独执行
go build main.go，而要用go build ./或go install ./——./表示递归构建当前目录下所有包，强制刷新全部依赖 - 如果还在用 GOPATH 模式，
go install server是触发依赖重编译的核心命令，不是可选项 - 强烈建议迁移到 Go Modules：在项目根目录执行
go mod init your-module-name，之后go build就不再受pkg/缓存干扰，行为完全基于源码和go.sum
实际升级时最容易被忽略的，是 go.mod 中的 go 指令与本地二进制版本的隐式耦合，以及 //go:build 对空白字符的零容忍——这两处不显眼，但一出错就卡死整个构建流程。
