Go 1.21起go指令为强制最低版本，不匹配则构建失败；CodeBuddy支持Go 1.19–1.23；需验证go version、go.mod、toolchain及CGO ABI一致性。
看 go version 和 go.mod 中的 go 指令是否匹配
Go 1.21 起，go 指令行工具会硬性校验 go.mod 里声明的 go 版本（如 go 1.21）是否 ≤ 当前 Go 工具链版本。不满足就直接报错：go: incompatible go version 1.23 not allowed by go.mod。这不是警告，是构建失败。
- 运行
go version查当前安装版本 - 打开项目根目录的
go.mod，找第一行go X.Y - 只要
X.Y≤ 实际版本即可；反过来（比如go 1.24但本地只有go 1.23）会失败
查 CodeBuddy 支持的 Go 最高/最低版本
CodeBuddy 官方文档明确支持 Go 1.19 到 1.23（截至 2026 年 5 月）。超出这个范围，补全、生成、错误提示可能失效或出错——不是模型“不会写”，而是语言服务器（gopls）和模型上下文对齐失败。
- VS Code 中启用 CodeBuddy 后，执行
go version，确认输出在1.19～1.23之间 - 若用
asdf管理多版本，进项目目录后运行go version必须和.tool-versions一致 - 别依赖 “它能跑通” 就认为兼容——补全延迟、跳转失效、类型推导不准，才是真实兼容性缺口
验证多模块项目中各子模块的 go 指令一致性
用 go.work 管理多个模块时，go 命令统一按工作区顶层的 go.mod 解析，但每个子模块仍保留自己的 go 指令。如果 ./auth-service/go.mod 写 go 1.20，而 ./shared/go.mod 写 go 1.22，go build ./... 可能成功，但 go test ./... 会在某些场景下因泛型解析差异失败。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 逐个进入子模块目录，运行
head -n1 go.mod查go行 - CI 流水线中禁用
go.work（加-modfile=go.mod），否则本地 OK、CI 报错 - 统一升级建议：用
go mod edit -go=1.22批量更新所有go.mod，再go mod tidy
检查 CGO 依赖链的 ABI 兼容边界
CGO 不是纯 Go 层面的兼容问题。比如你用 Go 1.22 编译调用 OpenSSL 的代码，但系统里装的是 OpenSSL 3.0，而 libcrypto.so 的符号表在 3.0 和 1.1.1 间有 ABI 断层——这时 go build 成功，./app 运行时报 undefined symbol: CRYPTO_free。这和 Go 版本无关，但属于环境兼容范围的关键盲区。
立即学习“go语言免费学习笔记（深入）”；
- 运行
ldd ./your-binary | grep crypto看实际链接的 so 文件路径 - 用
nm -D /path/to/libcrypto.so | grep CRYPTO_free验证符号是否存在 - 跨平台交叉编译时，必须用目标平台的 sysroot 或容器环境验证，不能只信本地
go version
go.work 的隐式耦合：前者要求底层库 ABI 稳定，后者要求各模块的 go 指令不冲突。这两点不显式验证，光看 go version 和文档支持范围，很容易漏掉运行时崩溃或 CI 构建失败。 
