Go安装后go version报错主因是PATH未正确配置，需手动添加GOROOT/bin；flag包需显式注册-h/--help；混用flag与pflag易panic；交叉编译须指定GOOS/GOARCH且禁用CGO；参数语义校验应在flag.Parse()后由业务逻辑完成。
Go 1.21+ 安装后 go version 报错或找不到命令
常见原因是 PATH 没配对，尤其在 macOS（zsh）或 Windows（PowerShell）下容易漏掉生效步骤。Go 官方安装包虽会尝试写入 $HOME/go/bin，但 go 命令本身（即 GOROOT/bin/go）仍需手动加入 PATH。
- macOS/Linux：检查
~/.zshrc或~/.bashrc是否包含export PATH=$PATH:/usr/local/go/bin（官方二进制安装路径）或export PATH=$PATH:$HOME/sdk/go/bin（SDKMAN 安装路径） - Windows：确认系统环境变量 PATH 中存在类似
C:\Program Files\Go\bin的条目，**不是**仅添加%USERPROFILE%\go\bin - 验证方式：新开终端运行
which go（macOS/Linux）或where go（Windows），输出应为有效路径；再执行go version看是否返回版本号
用 flag 包解析命令行参数时，-h 不触发帮助、--help 也不生效
flag 包默认只注册 -h 和 --help 当且仅当调用过 flag.Usage 或显式定义了对应 flag。它不会自动拦截并退出，更不会打印预设帮助文本。
- 必须在
flag.Parse()前，用flag.Bool("h", false, "show help")和flag.Bool("help", false, "show help")显式声明 - 解析后立即检查：
if *helpFlag || *hFlag { flag.Usage(); os.Exit(0) }—— 注意不能依赖flag.NArg() == 0判断，因为用户可能输错参数但仍想看帮助 - 自定义
flag.Usage更可靠：flag.Usage = func() { fmt.Fprintf(os.Stderr, "Usage: %s [options]\n", os.Args[0]); flag.PrintDefaults() }
pflag 和标准库 flag 混用导致 flag.ErrHelp 被忽略或 panic
项目里如果同时 import flag 和 github.com/spf13/pflag，且都调用了 Parse()，会出现未定义行为：比如 pflag.CommandLine.Parse() 后再调 flag.Parse()，后者可能因参数已被消费而报 flag: help requested 并 panic，尤其在测试中容易复现。
- 选一个包贯穿到底：新项目优先用
pflag（支持短长选项共存、子命令、类型丰富），老项目若无强需求，别引入pflag - 若必须桥接，用
pflag.CommandLine.AddGoFlagSet(flag.CommandLine)将标准 flag 集合并入 pflag，之后只调pflag.Parse() - 避免在
init()里提前调用flag.String()等 —— 这会让标准 flag 在 pflag 初始化前就注册，造成冲突
编译出的 CLI 工具在 Linux/macOS 上执行报 cannot execute binary file: Exec format error
这是典型的跨平台编译错误：你在 macOS 上用 GOOS=linux go build 生成了 Linux 二进制，却试图在 macOS 本地运行。Go 编译器默认产出当前系统的可执行文件，交叉编译需显式指定且注意 CGO。
立即学习“go语言免费学习笔记（深入）”；
- 确认目标平台：用
go env GOOS GOARCH查当前默认值；交叉编译时加GOOS=linux GOARCH=amd64 go build -o mytool-linux - 禁用 CGO 可避免动态链接问题：
CGO_ENABLED=0 GOOS=linux go build，否则可能因缺失libc报错 - Windows 用户想生成 Linux 版本？可以，但需确保代码不含 Windows-only API（如
syscall调用）；反之则不行 —— macOS 无法直接编译 Windows PE 文件
flag 包负责识别非法参数并退出，还是你的业务逻辑自己校验？答案是前者只管语法，后者管语义 —— 比如 -port -1 能被 flag.Int() 接收，但你得在 Parse() 后检查值是否合法。这点容易被跳过。 
