补全脚本必须由编译后的二进制生成，不能用 go run；函数名须严格匹配命令名（含软链），否则 shell 找不到入口；Cobra 仅输出函数定义，不自动注册，需手动 source 或配置 fpath/compinit 等。
补全脚本必须由编译后的二进制生成，不能用 go run；函数名必须严格匹配命令名（含软链场景），否则 shell 根本找不到补全入口。
为什么 mytool completion bash 生成的脚本不生效
根本原因不是脚本内容错，而是 shell 没加载它。Cobra 只输出函数定义（如 _mytool），不自动注册到当前 shell 环境。
- bash 下需手动执行
source /path/to/mytool.bash，或写入~/.bash_completion并确保该文件被/etc/bash_completionsource 过 - zsh 下必须满足三个条件：脚本文件名是
_mytool（下划线开头）、放在$fpath目录中、且已执行autoload -U +X compinit && compinit - macOS 上若用 Homebrew 安装 bash-completion，路径通常是
/usr/local/etc/bash_completion.d/；Linux 常用/usr/share/bash-completion/completions/ - 运行
complete -p | grep mytool（bash）或which _mytool（zsh）可快速验证是否加载成功
如何正确生成补全脚本（含软链和跨平台）
生成动作本身必须由最终用户使用的二进制触发，否则 os.Args[0] 错误会导致函数名污染（比如变成 _go 或 _tmp_main）。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 先编译：
go build -o mytool .，再运行：./mytool completion bash > mytool.bash - 如果用软链（如
ln -s mytool-v1.2 mytool），zsh 会默认注册_mytool_v1_2，导致失效；必须加--name mytool：./mytool completion zsh --name mytool > _mytool - PowerShell 补全需单独调用
cobra.GenPowerShellCompletion，并用Register-ArgumentCompleter注册；注意该 cmdlet 在某些策略下被禁用，报错The term 'Register-ArgumentCompleter' is not recognized时需检查执行策略 - fish 脚本路径固定为
~/.config/fish/completions/mytool.fish，写入后需source ~/.config/fish/config.fish或新开 shell
自定义补全时 RegisterFlagCompletionFunc 和 ValidArgsFunction 的坑
这两个函数不互斥，但触发时机和适用对象完全不同，混用或误用会导致补全静默失败。
立即学习“go语言免费学习笔记（深入）”；
-
RegisterFlagCompletionFunc("output", func(...)只对--output <TAB>有效；若光标停在--output<SPACE><TAB>，shell 默认走文件名补全，该函数不触发 -
ValidArgsFunction用于位置参数（如mytool deploy <env><TAB>），返回值不能含空字符串，建议用strings.TrimSpace预处理输入 - 布尔型 flag（如
--verbose）没有值，RegisterFlagCompletionFunc对它完全无效——这类 flag 不支持值补全 - 动态补全（如从 API 拉环境列表）务必预加载+缓存，避免每次 Tab 都发起 HTTP 请求；可用
time.Since(lastFetch) > 5 * time.Minute控制刷新频率
最容易被忽略的是 zsh 的 autoload 加载顺序和 bash-completion 包依赖：Alpine Linux 默认不装 bash-completion，补全会静默失效；而 macOS 新系统默认禁用非 Apple 补全，即使脚本放对位置也无反应。调试时别依赖 stdout，可在补全函数里写 log.Printf("debug: %v", args) >&2 并重定向 stderr 查日志。
