urfave/cli v3需导入github.com/urfave/cli/v3，用cli.Command定义命令并传context.Context调用Run()；Flag必须显式注册，Sources支持环境变量与配置文件自动联动。
urfave/cli 不是“学完再用”，而是“定义即可用”——只要正确声明 Command 或 App 结构体并调用 Run()，参数解析、帮助生成、错误提示就全有了。v3 是当前稳定主力版本，别默认拉 v2 或无版本号的旧版。
怎么选对版本并初始化一个可运行的 CLI 入口
直接用 v3，避免隐式兼容问题。v2 和 v1 的 cli.App 在 v3 中已统一为 cli.Command，且上下文类型强制为 context.Context。
初始化要点：
- 导入路径必须是
github.com/urfave/cli/v3，不是/v2或根路径 -
Run()第一个参数必须是context.Context，不能传nil（常见 panic 原因） -
os.Args可直接传入，但注意：它包含命令名，urfave/cli会自动跳过第一个元素解析子命令
最小可运行示例：
package main
import (
"context"
"os"
"github.com/urfave/cli/v3"
)
func main() {
cmd := &cli.Command{
Name: "hello",
Usage: "say hello",
Action: func(ctx context.Context, c *cli.Command) error {
println("Hello, world!")
return nil
},
}
if err := cmd.Run(context.Background(), os.Args); err != nil {
panic(err)
}
}
Flag 怎么设才不丢值、不报错
标志（Flag）不是靠手动从 c.String("x") 猜出来的——必须先在 Flags: 字段里显式注册，否则调用 c.String() 会 panic 或返回空字符串（无提示）。
立即学习“go语言免费学习笔记（深入）”；
常见陷阱：
-
Value是默认值，不是初始值；它只在 flag 未被传入时生效，**不会覆盖环境变量或配置文件中的值**（除非你没配Sources） - 布尔 flag 不支持
=赋值写法：--verbose=true会报错，只能写--verbose或--no-verbose -
Required: true仅校验 flag 是否出现，不校验值是否为空字符串（比如--name ""仍算通过） - 别名（
Aliases）必须是单字符或短字符串，且不能与其它 flag 名冲突，否则启动时直接 panic
安全写法示例：
&cli.StringFlag{
Name: "output",
Aliases: []string{"o"},
Value: "stdout",
Usage: "output destination",
Required: false,
}
怎么让 --help 真正有用，而不是只列 flag
urfave/cli 自动生成 help，但默认只显示 flag 名和 Usage 字符串。要提升可读性，得主动补全三类信息：
-
Usage：一句话说明用途（必填），太长会被截断 -
Help：完整说明段落，会在--help的 flag 列表下方展开显示 -
Category：把相关 flag 分组，比如Network Options、Auth Options，需配合cli.WithCategory使用
示例：
&cli.StringFlag{
Name: "host",
Usage: "server host address",
Help: "IP or domain name. Defaults to 'localhost' if not set.",
Category: "Network",
}
注意：Help 字段 v3 才正式支持，v2 中无效；若用了 v2 却写了 Help，会被静默忽略。
环境变量和配置文件怎么和 Flag 自动联动
靠 Sources 字段，不是靠手写 os.Getenv()。框架会在 flag 未传入时，按 Sources 中顺序查找值源。
典型组合：
- 环境变量优先：
Sources: cli.EnvVars("MYAPP_HOST", "HOST") - 配置文件兜底：
Sources: cli.Files("/etc/myapp/config.yaml")（需搭配urfave/cli-altsrc/v3解析 YAML/JSON） - 多源链混合：
Sources: cli.NewValueSourceChain(cli.EnvVars("APP_PORT"), cli.File("/etc/port"))
关键限制：
-
cli.EnvVars()只读取字符串，不自动转类型（IntFlag仍需自己strconv.Atoi()） - 配置文件路径必须存在且可读，否则整个 flag 初始化失败，导致
Run()panic -
urfave/cli-altsrc是独立包，不包含在主库中，必须额外go get
最简环境变量生效示例：
&cli.StringFlag{
Name: "region",
Value: "us-east-1",
Sources: cli.EnvVars("AWS_REGION", "REGION"),
}
然后执行 AWS_REGION=cn-north-1 ./myapp，c.String("region") 就返回 "cn-north-1"。
urfave/cli 的核心复杂点不在语法，而在「值源优先级」和「flag 注册时机」——漏注册、错版本、Sources 顺序颠倒，都会导致行为静默异常。动手前先跑通最小 Command + 单个 StringFlag + EnvVars 链，比看十页文档更管用。 
