click.group()是子命令脚手架的起点，因为只有group实例才能作为容器注册子命令；@click.command()生成的孤立命令无法挂载子命令，必须通过@click.group()创建主入口并统一注册子命令。
为什么 click.Group() 是子命令脚手架的起点
因为 Click 不靠装饰器堆叠实现多级命令，而是依赖 click.Group 实例作为命令容器。直接用 @click.command() 写出来的函数无法挂载子命令——它只是个孤立命令。必须显式创建一个 click.Group 实例（或用 @click.group() 装饰），才能调用 .add_command() 或通过装饰方式注入子命令。
常见错误是写完几个 @click.command() 函数后试图“连起来”，结果运行时提示 No such command。本质是没把它们注册到同一个父 group 下。
- 主入口函数必须用
@click.group()装饰，不能用@click.command() - 子命令函数可以是普通函数，但必须用
@cli.command()（其中cli是 group 实例）注册 - group 实例名（如
cli）会成为 CLI 的一级命令名，比如python mytool.py init中的mytool.py后紧跟的就是它
如何组织子命令参数与共享选项
子命令各自需要不同参数，但有些选项（如 --verbose、--config）应全局生效。Click 不支持跨命令自动透传，得手动处理：在 group 层级定义共享参数，并通过 context 传递给子命令回调。
典型做法是让 group 的回调函数接收参数并存入 ctx.obj，子命令再从 ctx.obj 取值。否则每个子命令都重复定义 --verbose，不仅冗余，还导致 --help 输出混乱。
- group 回调需加
@click.pass_context，并在函数内执行ctx.obj = {...} - 子命令函数也加
@click.pass_context，然后读取ctx.obj.get("verbose") - 避免在子命令里重新定义已由 group 处理的选项，否则会冲突报错
Option 'verbose' is declared in the function - 如果某个子命令需要独有且必填的参数，直接用
@click.argument("name")，别塞进共享逻辑里
子命令模块化拆分后怎么正确导入
脚手架变大后，没人愿意把十几个子命令全堆在一个文件里。Click 支持模块化，但 import 时机和对象引用容易出错——最常见的是 ImportError 或子命令不显示。
关键不是“能不能 import”，而是“import 后有没有真正注册”。如果只写了 from commands.init import init_cmd 却没调用 cli.add_command(init_cmd)，那这个命令就不存在。
- 推荐做法：每个子命令模块导出一个
click.Command实例（如init），主文件统一 import 并注册 - 不要在子命令模块里调用
cli.add_command(...)——会造成循环 import 或未初始化就注册 - 如果用包结构（如
commands/目录），确保__init__.py里不触发实际命令注册，只做符号导出 - 调试时可打印
cli.list_commands(ctx)验证当前注册了哪些子命令
为什么 --help 显示异常或子命令不列出来
根本原因通常是 group 实例没有被最终调用。比如写了 cli = click.Group()，也写了 cli.add_command(init)，但最后忘了 cli() 或 cli(auto_envvar_prefix="MYTOOL") 这样的执行入口。
另一个高频问题是子命令函数名和注册名不一致：默认注册名是函数名，但如果用了 @cli.command(name="new")，那 help 里显示的就是 new，不是函数名 init_cmd。用户按函数名试，自然找不到。
- 检查脚本末尾是否有
if __name__ == "__main__": cli() - 运行
python mytool.py --help应该列出所有子命令；如果只显示Options:没有Commands:，说明 group 为空 - 子命令帮助文本来自函数的 docstring，不是装饰器参数，别在
@cli.command(help="...")里写描述指望它覆盖 - Windows 下若遇到编码错误导致 help 显示乱码，加环境变量
PYTHONIOENCODING=utf-8或在代码开头设sys.stdout.reconfigure(encoding="utf-8")（Python 3.7+）
ctx.obj 导致内存常驻。这些不会立刻报错，但会让脚手架在长期维护中变得难以调试。Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
