Go标准库flag包不支持补全，因其仅解析参数、不参与shell交互；补全需shell驱动并由外部逻辑实现，推荐用spf13/cobra内置支持，手动实现时须按shell类型输出对应格式，并缓存候选值防卡顿。
为什么 flag 包本身不支持补全
Go 标准库的 flag 包只负责解析命令行参数，完全不介入 shell 层交互。它既不读取 TAB 键输入，也不生成补全脚本——补全行为必须由 shell（如 bash/zsh）驱动，靠外部脚本或二进制钩子提供候选词。
这意味着：你不能靠改 flag.Parse() 就让终端自动弹出子命令列表；必须额外提供 shell 可调用的补全逻辑，并注册到对应 shell 的补全机制中。
- bash 通过
complete -F _mytool mytool调用函数_mytool - zsh 依赖
_mytool函数 +compdef _mytool mytool - 你的 Go 程序需要能响应类似
mytool __complete subcmd --fo<TAB>这类特殊调用，输出换行分隔的候选字符串
用 spf13/cobra 快速接入补全（推荐路径）
cobra 是 Go CLI 工具事实标准，它内置了对 bash/zsh/fish 补全的支持，原理是：当检测到 __complete 子命令时，跳过常规执行流程，直接调用内部补全器生成候选项。
关键点不是“写补全逻辑”，而是“让 cobra 知道哪些字段可补全”：
- 为
cmd.Flags().StringVarP(&file, "file", "f", "", "input file")添加补全标记：cmd.RegisterFlagCompletionFunc("file", completeFilename) - 为子命令补全（如
mytool deploy <env>）：在deployCmd的ValidArgsFunction字段返回[]string{"prod", "staging", "dev"} - 补全函数签名必须是
func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)
生成脚本只需一行：rootCmd.GenBashCompletionFile("mytool.bash")，然后用户 source mytool.bash 即可生效。
手动实现补全时如何避免 zsh 兼容性翻车
zsh 对补全输出格式更敏感：每行必须是 value[tab]description（带 tab 分隔），且末尾不能有多余空行；bash 则只要纯 value 换行即可。如果统一用 bash 方式输出，zsh 会静默失败——看起来像没补全。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
正确做法是：在补全入口判断 os.Args[1] == "__complete" 后，立刻检查 os.Getenv("COMP_SHELL")：
- 值为
zsh→ 输出"prod\tproduction env\nstaging\tstaging env\n" - 值为
bash→ 输出"prod\nstaging\ndev\n" - 未设置或为
fish→ 用 fish 要求的 JSON 格式（{"options": [{"name": "prod", "description": "production env"}]}）
别硬编码 COMP_SHELL：zsh 下该变量恒为 zsh，bash 下为 bash，fish 下为 fish——这是各 shell 注入的可靠标识。
补全候选值动态加载时的性能陷阱
如果补全项来自远程 API 或本地大文件（比如列出 S3 bucket 内容），每次 TAB 都触发一次 HTTP 请求或磁盘扫描，会导致明显卡顿甚至超时失效。
解决方案不是“优化请求”，而是“规避实时加载”：
- 首次运行时缓存候选列表到
$XDG_CACHE_HOME/mytool/completions.json，补全时只读缓存 - 用
time.Now().Sub(cacheModTime) < 5*time.Minute控制刷新频率 - 对模糊匹配场景（如
mytool logs --pod nginx<TAB>），先用本地缓存前缀过滤，命中率低时再懒加载
用户不会感知“补全慢”，只会觉得“补全没反应”——所以宁可返回旧数据，也不要阻塞 shell。
