根本原因是未调用rootcmd.execute()——它驱动命令树加载，必须作为main()最后一行执行；rootcmd须为包级变量并由cmd/root.go初始化，子命令需在execute()前注册。
根命令没执行 rootCmd.Execute()，所有子命令都不可用——这是 90% 的“命令找不到”问题的根源。
为什么 rootCmd.Execute() 必须放在 main() 最后一行
Cobra 的命令树是惰性加载的：Execute() 才真正触发解析、匹配和执行流程。不调它，cmd.AddCommand() 注册的子命令压根不会被注册进运行时上下文。
-
rootCmd必须是包级变量（不能在函数里 new 出来再 return），且由cmd/root.go初始化 - 子命令必须在
Execute()调用前完成挂载，常见位置是init()或main()开头 - 别用
ExecuteC()除非你手动处理返回的error和*Command；默认就用Execute() - 如果用了
cobra-cli init生成骨架，检查main.go是否只剩cmd.Execute()这一行（无其他逻辑）
flag.StringP() 参数顺序写反会导致 panic
短选项名必须是单字符，且固定在第二个参数位；写错会直接 panic：“invalid shorthand format”。
- 正确：
cmd.Flags().StringP("config", "c", "./config.yaml", "配置文件路径") - 错误：
cmd.Flags().StringP("config", "./config.yaml", "c", ...)—— 把默认值放到了短选项位置 - 短选项不能是空字符串或多个字母，
"cfg"或""都非法 - 多个子命令若都注册了
-v，后注册的会覆盖前一个，但无警告；可用cmd.Flags().Lookup("v").Usage检查是否被意外覆盖
子命令里 panic 不报错，只静默退出
Run 函数内 panic 会被 Cobra 捕获并吞掉，用户看到的是“没反应”或直接退出，没有任何提示。
- 一律改用
RunE：签名是func(*cobra.Command, []string) error，返回 error 即可 - 在
RunE开头加defer func() { if r := recover(); r != nil { cmd.Println("panic:", r) } }()，避免崩溃无声 - 别在
init()里读配置、连数据库——这些操作失败会阻断整个 CLI 启动；移到RunE中显式处理 - 如果用了 Viper，确保
viper.BindPFlags(cmd.Flags())在RunE之前调用，否则viper.GetString("xxx")取不到 flag 值
help 对齐错乱、中文显示异常
这不是 Cobra bug，而是 Go 标准库 text/tabwriter 在跨平台交叉编译时对宽字符（如中文）和 \t 的渲染不一致导致的。
- 典型现象：help 输出中选项列右移错位、中文后多出空白、
-h显示不全 - 临时解决：编译时加
-tags=notabwriter（禁用 tabwriter） - 长期建议：避免在
Short/Long字段里混用中英文对齐描述；用纯英文 help + 外部文档补充中文说明 - 别依赖
Args校验自动补全——cobra.ExactArgs(2)只影响运行时校验，不影响 shell 补全行为
最易被忽略的一点：Viper 绑定 flag 后，viper.Get("port") 和 cmd.Flag("port").Value.String() 返回值可能不同——前者走优先级合并（flag > env > file），后者只取 flag 值。调试时务必确认你读的是哪一层。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
