Click 不提供美观界面，美观靠分组、帮助文本、颜色和参数设计实现；多命令需用 @click.group() 组织，子命令定义参数，路径校验用 click.Path() 更可靠，--help 应精简默认值并写清用途，输出区分 echo()（结构化）与 secho()（交互式颜色）。
Click 本身不提供“美观”界面，所谓美观实际是靠合理分组、帮助文本格式、颜色提示和参数设计实现的；直接套模板反而容易让 CLI 变得臃肿难维护。
如何用 @click.group() 组织多命令结构
单命令工具用 @click.command() 就够了，但一旦命令超过 3 个，立刻需要分组——否则 --help 输出会变成一长串难以定位的选项列表。
- 顶层
@click.group()必须带invoke_without_command=True才能在不输子命令时显示帮助或默认行为 - 子命令函数不要加
@click.option()到 group 函数上，那是无效的；所有参数必须定义在具体子命令里 - group 的
help参数会被忽略，真正起作用的是子命令自己的help字符串
@click.group()
def cli():
pass
@cli.command()
@click.option('--verbose', is_flag=True)
def build(verbose):
"""Build the project."""
pass
为什么 type=click.Path() 比手动 os.path.exists() 更可靠
路径校验不是简单判断文件是否存在——还要处理相对路径解析、权限检查、是否为目录等。Click 内置类型自动做这些，且错误提示更友好。
-
exists=True：只校验存在性，不区分文件/目录 -
file_okay=False+dir_okay=True：强制要求是目录（比如指定输出路径） -
resolve_path=True：自动展开~和.，避免用户输~/data时程序报错 - 注意：
click.Path()不会自动创建父目录，mkdir -p还得自己调os.makedirs(..., exist_ok=True)
怎样让 --help 输出真正有用，而不是堆满默认值
Click 默认把所有参数默认值都打出来，但像 default=None 或 default=[] 这类值只会干扰阅读。
python-script-generator
下载
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
立即学习“Python免费学习笔记（深入）”；
- 用
show_default=False关掉默认值显示，除非该默认值有业务意义（比如--timeout 30） - 把长说明写进
help字符串，用换行分隔逻辑段，Click 会自动缩进排版 - 避免在
help里写“必填”或“选填”，Click 已通过required=True/False控制，重复描述反而增加维护成本 - 如果某个选项只在特定场景下有效，用
hidden=True隐藏它，别指望用户靠文档发现“隐藏功能”
颜色和进度条不是必须的，但 echo() 和 secho() 要分清用途
Click 提供 click.echo() 和 click.secho()，前者纯文本输出，后者支持颜色和样式。关键区别在于：前者输出可被管道重定向（cmd --json | jq），后者在终端外会带 ANSI 转义字符，破坏 JSON 格式。
- 日志类输出（如 “Starting…”, “Done.”）用
secho()加fg='green'，但仅限交互式场景 - 结构化输出（JSON/YAML/TSV）必须用
echo()，哪怕看起来“不够美观” - 进度条（
click.progressbar()）只适合耗时 >1s 的操作，短任务加进度条反而让用户觉得卡顿 - 别用
print()，它绕过 Click 的输出控制，会导致颜色失效、编码错误、测试 mock 困难
真正难的不是加颜色，而是判断什么时候不该加——尤其是当你的 CLI 被别人脚本调用时，任何非结构化输出都是隐患。
