Go-flags初始化必须在main函数开头立即调用，定义配置结构体并解析；子命令需显式注册且不自动继承父flag；环境变量优先级低于命令行参数；热重载应避免复用parser，改用独立配置管理。
Go-flags 初始化必须在 main 函数早期调用
Go-flags 不是“按需加载”的库，它依赖全局解析状态，如果在子包或延迟初始化的模块里才调用 flags.Parse，会导致参数未生效、默认值被忽略，甚至 panic（比如 flag provided but not defined）。最稳妥的做法是：在 main() 开头就完成结构体定义和解析。
- 定义一个顶层配置结构体，用
flag标签声明字段（如Port int `long:"port" default:"8080" description:"HTTP server port"`） - 用
flags.NewParser创建 parser 实例（推荐传入nil作为命令名，避免意外触发子命令逻辑） - 立即调用
parser.Parse，不要包裹在 init() 或其他函数里 - 检查返回的
err，flags.ErrHelp是正常退出信号，应直接 return，不视为错误
子命令支持需要显式注册且共享基础 flag
Go-flags 默认只处理顶级参数。想支持类似 ./app serve --port=3000 或 ./app migrate --env=prod 这种结构，必须手动注册子命令，并注意 flag 作用域——父命令定义的 flag 不会自动透传给子命令。
- 每个子命令需实现
flags.Commander接口，其中Execute方法接收*flags.Connector参数 - 若需复用通用 flag（如
--config），应在主 parser 上定义，再通过parser.FindOptionByLongName手动提取并传递给子命令逻辑 - 子命令的
Usage字段影响 help 输出格式，建议保持简短（如"serve - start HTTP server"），否则 help 页面会错位 - 子命令名称不能含空格或特殊字符，否则
Parse会报unknown command
环境变量与 flag 冲突时以 flag 为准
Go-flags 支持通过 env:"CONFIG_PATH" 标签读取环境变量，但它的行为是“覆盖式”：命令行 flag > 环境变量 > 默认值。这点容易误判——你以为设置了 CONFIG_PATH=/etc/app.yaml 就能 fallback，结果加了 --config=local.yaml 却没生效，其实是 flag 优先级更高。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 确认字段标签同时包含
env和long（如ConfigPath string `long:"config" env:"APP_CONFIG" default:"config.yaml"`） - 调试时用
flags.NewParser(..., flags.Default).Parse(os.Args)并捕获返回的err，可打印出实际解析结果（parser.Visit遍历所有已设置选项） - 避免在 struct 字段上混用
short和env：short flag（如-c）无法触发 env 变量读取，只有 long flag 或无 flag 时才查 env
热重载配置时别直接复用 Go-flags 解析结果
Go-flags 的设计目标是一次性解析启动参数，不是运行时配置管理器。如果你在服务中监听文件变更并试图重新调用 parser.Parse，会遇到两个问题：一是 parser 内部状态不可重置，二是新解析可能覆盖已有字段但不触发验证逻辑。
立即学习“go语言免费学习笔记（深入）”；
- 启动阶段用 Go-flags 解析初始配置，存为不可变结构体（如
type Config struct { ... }） - 运行时热重载应走独立路径：读取 YAML/JSON 文件 → unmarshal → 校验 → 替换内存中 config 实例（建议用
sync.RWMutex保护） - 如果坚持要用 Go-flags 做热重载，必须新建 parser 实例，并确保所有字段 tag 完全一致，否则字段映射会错乱
真正麻烦的不是怎么写 flag，而是什么时候不该用它——启动参数归启动参数，运行时配置归运行时配置，混在一起只会让 reload 逻辑变成定时炸弹。
