Click命令补全默认不生效是因为Click不自动注册shell补全脚本，需手动运行your_script.py --install-completion并重载配置文件（如source ~/.bashrc）；子命令补全需显式启用装饰器且避免invoke_without_command=True导致解析提前退出。
Click 命令补全在 Bash/Zsh 下为什么默认不生效
因为 Click 本身不自动注册 shell 补全脚本，必须手动触发生成并加载。没做这步，tab 按下去只会响一下——不是你的代码写错了，是 shell 根本不知道该补谁。
实操分两步：
- 运行
your_script.py --install-completion（Click 8.0+ 内置命令），它会把补全脚本写入对应 shell 的配置文件（如~/.bashrc或~/.zshrc） - 执行
source ~/.bashrc（或source ~/.zshrc）重载配置，否则补全逻辑不会加载进当前 shell - 注意：如果用的是非标准 shell（如 fish），需额外加
--shell fish参数；Windows PowerShell 用户要指定--shell powershell
自定义参数补全时，shell_complete 和 autocompletion 到底用哪个
Click 7.x 用 autocompletion 参数，8.x 起已弃用，统一改用 shell_complete 回调函数。混用会导致补全静默失败，且无报错提示。
正确写法示例：
立即学习“Python免费学习笔记（深入）”；
@click.option('--env',
shell_complete=lambda ctx, args, incomplete: [
'dev', 'staging', 'prod'
])
关键点：
-
shell_complete函数必须返回list[str]，不能是生成器或元组 - 函数签名固定为
(ctx, args, incomplete)，其中incomplete是当前未输完的字符串，可用于过滤（比如只返回匹配incomplete开头的选项） - 如果返回空列表，shell 会 fallback 到文件路径补全，这不是 bug，是设计行为
补全候选值含空格或特殊字符时怎么避免被 shell 截断
比如想补全 "test env" 这种带空格的值，直接返回会导致 shell 把它拆成两个词，补全失效。
解决办法只有两个：
- 用下划线替代空格：
"test_env"，再在命令逻辑里做映射（最稳妥） - 对每个候选值手动加引号并转义，例如返回
['"test env"', '"prod db"']，但部分 shell（尤其是旧版 Bash）支持不稳定，Zsh 更友好些 - Click 不处理 shell 层面的引号转义，这是你回调函数的责任——别指望
shell_complete自动帮你包双引号
为什么子命令补全有时不工作，或者只补父命令不补子命令
Click 默认只对顶层命令启用补全，子命令（@click.group() 下的 @click.command()）需要显式开启，否则 mytool subcmd <tab> 不会触发补全逻辑。
必须确保：
- 子命令函数也加上
@click.command()装饰器（不能只用@click.group()包裹） - 所有层级的命令都通过
click.Command或其子类实例化（即避免用裸函数 +group.add_command()动态注册，除非手动设置command.shell_complete） - 补全脚本安装后，检查生成的 completion 文件里是否包含子命令的解析逻辑——如果没出现，说明 Click 在扫描时没识别到该命令
复杂 CLI 结构里，最容易被忽略的是 group 的 invoke_without_command=True 配置，它会让 Click 提前退出命令解析，导致子命令补全注册失败。
