flag.String、flag.Int等必须在flag.Parse()前调用，否则参数无法识别且访问会panic；自定义类型需实现flag.Value接口；重写flag.Usage时须显式调用flag.PrintDefaults()；子命令应使用flag.NewFlagSet避免冲突。
flag.String、flag.Int 等函数必须在 flag.Parse() 前调用
Go 的 flag 包是惰性绑定：声明参数时只是注册，真正从 os.Args 解析并赋值要等到 flag.Parse() 执行。如果在 flag.Parse() 之后再调用 flag.String()，该参数永远不会被识别，且后续访问会 panic（比如对 nil 指针解引用）。
常见错误写法：
port := flag.Int("port", 8080, "server port")
flag.Parse()
// ... 业务逻辑
flag.Bool("debug", false, "enable debug mode") // ❌ 错误：Parse 后不能再注册
正确顺序应为：
- 所有
flag.Xxx()调用放在最前面（通常紧贴main()开头） - 然后统一调用
flag.Parse() - 最后通过返回的指针或变量读取值
自定义类型需实现 flag.Value 接口才能用 flag.Var
当需要支持复杂参数类型（如逗号分隔的字符串切片、自定义结构体、时间范围等），不能直接用 flag.StringSlice 硬凑，而应实现 flag.Value 接口（含 Set(string) error 和 String() string）。否则解析失败时只会静默忽略或报 “invalid value” 错误。
立即学习“go语言免费学习笔记（深入）”；
例如支持 -tags=a,b,c：
type tagsValue []string
func (t *tagsValue) Set(s string) error {
*t = strings.Split(s, ",")
return nil
}
func (t *tagsValue) String() string { return strings.Join(*t, ",") }
var tags tagsValue
flag.Var(&tags, "tags", "comma-separated list of tags")
注意点：
- 必须传指针给
flag.Var()，否则Set()修改的是副本 -
String()返回值用于-h输出展示，不参与解析 - 若
Set()返回非 nil error，flag.Parse()会终止并打印错误退出
flag.Usage 自定义帮助输出时别漏掉 flag.PrintDefaults()
默认的 -h 或无效参数提示只显示你注册的 flag，但不会自动列出每个 flag 的默认值和说明。如果重写了 flag.Usage 却没手动调用 flag.PrintDefaults()，用户执行 ./app -h 就只能看到空泛提示，完全不知道有哪些参数可选。
正确做法：
flag.Usage = func() {
fmt.Fprintf(os.Stderr, "Usage: %s [flags] \n", os.Args[0])
fmt.Fprintf(os.Stderr, "Flags:\n")
flag.PrintDefaults() // ✅ 必须显式调用
}
其他易错细节：
-
flag.Usage是一个函数变量，需在flag.Parse()前设置才生效 - 帮助文本输出到
os.Stderr，不是os.Stdout，符合 Unix 习惯 - 若用
flag.CommandLine = flag.NewFlagSet(...)创建子命令，每个 set 需单独设置Usage
子命令场景下避免全局 flag 冲突用 flag.NewFlagSet
像 git commit、go test 这类带子命令的工具，不同命令可能有同名但语义不同的 flag（如 go build -o 和 go run -o），用全局 flag 包会导致冲突或覆盖。此时必须用 flag.NewFlagSet(name, errorHandling) 为每个子命令创建独立命名空间。
关键点：
- 第二个参数常用
flag.ContinueOnError，这样解析失败时不会 os.Exit，便于你自己处理错误并打印子命令帮助 - 每个
FlagSet需单独调用Parse()，且传入对应子命令后的参数切片（如args[2:]） - 不要混用
flag.Xxx()（操作全局 FlagSet）和fs.Xxx()（操作局部 FlagSet）
典型结构：
if len(os.Args) < 2 {
usage()
os.Exit(1)
}
switch os.Args[1] {
case "serve":
fs := flag.NewFlagSet("serve", flag.ContinueOnError)
port := fs.Int("port", 8080, "listen port")
if err := fs.Parse(os.Args[2:]); err != nil {
log.Fatal(err)
}
startServer(*port)
这里最容易被忽略的是：子命令的参数起始索引计算错误，导致把子命令名本身也当作 flag 值传进去，引发 “unknown flag” 报错。
