Cobra构建CLI必须避免三大坑：flag绑定须用子命令自身Flags()而非rootCmd，Execute()必须作为main()最后一行调用以驱动命令树加载，help文本需在command初始化时通过Short/Long/Example字段显式设置且命名与实际注册一致。
Go 用 Cobra 写命令行工具，不是“能不能”，而是“怎么避免掉坑里”。它确实能快速搭出带子命令、flag、自动 help 的 CLI，但默认行为和常见配置组合稍不注意就会导致 flag 解析失败、命令嵌套混乱、或 help 文本错乱。
为什么 cmd.Execute() 一调就 panic: "flag provided but not defined"
这是最常卡住新手的错误——你在某个子命令里用了 rootCmd.Flags().StringVarP，却忘了在该子命令自己的 cmd.Flags() 上注册；或者把 flag 绑定到了错误的命令实例上。Cobra 不会跨命令共享 flag，每个 Command 实例必须显式声明自己要解析哪些 flag。
- 子命令要用自己的
cmd.Flags()，而不是复用rootCmd.Flags() -
StringVarP第一个参数必须是已声明的变量地址（&myVar），不是变量名 - 如果用了
PersistentFlags()，它会被子命令继承，但普通Flags()不会 - 执行前确保
cmd.Execute()调用的是你最终构建好的命令树顶层实例（通常是rootCmd）
如何让 --help 显示你写的 Usage 示例和自定义说明
默认 help 是机械拼接出来的，不直观。Cobra 允许你覆盖 Short、Long、Example 字段，但关键在于：这些字段必须在 command 初始化时赋值，且 Example 中的命令名要和实际注册的一致（比如 root 命令叫 mytool，示例就得写 mytool serve --port 8080）。
-
Short控制 help 列表里的单行摘要（显示在mytool [command]后面） -
Long是--help里展开的详细说明，支持换行，但别加多余空行（会多出空段落） -
Example必须是字符串，换行用\n，且第一行通常应为命令本身（如mytool config set token abc123） - 别在
init()里改这些字段——此时Command实例可能还没完全初始化
子命令参数和 flag 混用时，为什么 args 总是空或顺序错乱
Cobra 默认把所有非 flag 内容都当 args，但如果你在子命令里启用了 Args: cobra.ExactArgs(1) 却传了 cmd --verbose file.txt，它会把 --verbose 当作 flag 解析完后，才把 file.txt 交给 args。问题常出在：没设 Args 验证、或误把位置参数写在 flag 前面（如 mytool file.txt --verbose），而 Cobra 不支持 flag 位置浮动（除非启用 Command.TraverseChildren = true 并手动处理）。
立即学习“go语言免费学习笔记（深入）”；
- 位置参数必须严格放在所有 flag 之后，否则会被当作未知 flag 报错
- 用
cobra.MinimumNArgs(1)或cobra.ArbitraryArgs替代硬编码数量，更灵活 - 若真需要 flag 在参数前，得在
PreRun或Run里手动解析cmd.Args()，并禁用默认 args 校验（Args: nil） -
cmd.Flags().SetInterspersed(false)可禁止 flag 和参数交错（默认 true），但仅影响当前命令
为什么 go run main.go 正常，打包成二进制后 --help 里命令名变成 main
因为 rootCmd.Use 默认取 os.Args[0]，而 go run 下它是 main.go 所在路径，打包后直接运行二进制时 os.Args[0] 就是 main。Cobra 不会自动从二进制文件名推导命令名。
- 显式设置
rootCmd.Use = "mytool"（不能含路径，只留命令名） - 同时设
rootCmd.Short = "My awesome CLI tool"，避免 help 顶部显示main - 如果支持多级命令（如
mytool cloud deploy），确保每层Use都准确（"cloud"、"deploy"），不要用"mytool cloud" - 别依赖
filepath.Base(os.Args[0])动态取名——交叉编译时可能不可靠
真正麻烦的从来不是写命令，而是 flag 绑定时机、args 边界判定、以及 help 文本和实际行为的同步。哪怕只加一个子命令，也得检查三遍 Flags() 归属、Args 约束、Use 命名——漏一处，用户跑起来就是报错或误导。
