flag不支持子命令嵌套，需手动切分args并为各子命令创建独立FlagSet；cobra中RunE返回错误需避免panic/os.Exit；viper实现配置三级优先级需正确绑定flag与env；交叉编译失败多因cgo动态链接问题。
为什么不用 flag 包直接解析就出问题？
很多初学者一上来就用 flag.String 或 flag.Int，结果发现子命令（如 mytool serve 和 mytool migrate）没法区分，或者参数位置一变就报错。这是因为 flag 默认只处理全局参数，不支持嵌套命令树，且会自动消费所有后续参数——哪怕你本意是留给子命令用的。
解决办法是：在调用 flag.Parse() 前，先手动切分 os.Args，识别出第一个非标志参数作为子命令名，再把剩余参数传给对应子命令的独立 flag.FlagSet 实例。这样每个子命令都有自己的参数命名空间，互不干扰。
- 永远不要对整个
os.Args调用一次flag.Parse() - 子命令的
FlagSet必须设置ErrorHandling为flag.ContinueOnError，否则出错直接退出主流程 -
FlagSet.Parse()传入的是从子命令开始的参数切片（比如os.Args[2:]），不是原始os.Args
用 spf13/cobra 时为什么 RunE 返回错误却不打印？
cobra.Command.RunE 是推荐的入口函数，它返回 error，但默认情况下这个 error 不会自动输出到 stderr——除非你显式调用 cmd.SilenceErrors = false（这是默认值），且没设置 SilenceUsage = true。更常见的情况是：你在 RunE 里 panic 了，或调用了 log.Fatal，导致程序提前终止，根本没走到 cobra 的错误处理逻辑。
正确做法是让 RunE 返回 error，由 cobra 统一处理输出和退出码：
立即学习“go语言免费学习笔记（深入）”；
func(cmd *cobra.Command, args []string) error {
if len(args) == 0 {
return fmt.Errorf("missing required argument: filename")
}
// 处理逻辑...
return nil
}
- 不要在
RunE中调用os.Exit()、log.Fatal()或panic() - 若需自定义错误输出格式，可设置
cmd.SetErr()指向自定义io.Writer - 使用
cmd.ExecuteContext(ctx)替代cmd.Execute()，便于支持超时和取消
如何让 CLI 工具支持配置文件 + 环境变量 + 命令行参数三级优先级？
用户希望命令行参数覆盖环境变量，环境变量覆盖配置文件（如 config.yaml）。Go 标准库不提供开箱即用的层级合并，得自己串起来。推荐用 spf13/viper，但它默认行为容易踩坑：比如未显式调用 viper.BindPFlag()，命令行参数就不会写入 viper 的值空间；又比如 viper.AutomaticEnv() 默认前缀是二进制名全大写，而很多人习惯用 MYTOOL_ 这样的前缀。
关键步骤：
- 先
viper.SetConfigFile("config.yaml")并viper.ReadInConfig()，捕获viper.ConfigFileNotFoundError可忽略 - 调用
viper.AutomaticEnv()后，立刻viper.SetEnvPrefix("mytool")（小写，viper 会自动转成大写+下划线） - 对每个 flag 调用
viper.BindPFlag("key.name", rootCmd.Flags().Lookup("name"))，注意 key 名要和 config 文件里的字段路径一致（如server.port） - 读值统一用
viper.GetInt("server.port")，不用flag或os.Getenv
交叉编译后 CLI 工具在目标系统上启动失败，常见原因是什么？
用 GOOS=linux GOARCH=amd64 go build 编译出来的二进制，在 Linux 上运行报 no such file or directory，其实不是缺文件，而是缺动态链接器（尤其是用了 cgo 的情况）。默认 Go 构建是 CGO_ENABLED=1，会链接 libc，但 Alpine 或某些精简镜像只有 musl libc。
解决方案取决于是否真需要 cgo：
- 如果不需要（比如纯网络/文件操作工具），构建前设
CGO_ENABLED=0，生成完全静态二进制 - 如果必须用 cgo（如调用 SQLite、OpenSSL），则要么用
golang:alpine镜像构建，要么在目标系统装libc6-compat（Alpine）或glibc（CentOS/RHEL） - 检查依赖：运行
ldd your-binary，若显示not a dynamic executable，说明已是静态；若列出一堆libc.so，就是动态链接问题
静态编译的二进制体积稍大，但部署简单——这点权衡在 CLI 工具里几乎总是值得的。
