flag.String 和 flag.Int 等必须在 flag.Parse() 前调用，因其仅注册参数；Parse() 后调用无效，变量保持零值；子命令需用 flag.NewFlagSet，自定义类型需实现 flag.Value 接口。
flag.String 和 flag.Int 等基础类型函数必须在 flag.Parse() 前调用
Go 的 flag 包是惰性初始化的：所有 flag.String、flag.Int、flag.Bool 等函数只是注册参数，并不立即解析。一旦调用 flag.Parse()，它才会真正扫描 os.Args[1:] 并赋值。如果在 flag.Parse() 之后再调用 flag.String，该参数不会被识别，也不会报错，但读取时始终为空或零值。
常见错误现象：flag.String("config", "", "config file path") 写在 flag.Parse() 后面，运行时传入 -config=config.yaml，但变量值仍是空字符串。
- 所有
flag.Xxx()调用必须放在flag.Parse()之前 - 推荐统一放在
main()开头，或封装进initFlags()函数并在main()最早处调用 - 不要试图“按需注册 flag”——动态注册不生效
自定义 flag.Value 接口实现复杂参数类型（如 []string 或 map[string]string）
内置的 flag.StringSlice 只支持逗号分隔的单个字符串（如 -tags=a,b,c），无法处理多次出现的同名 flag（如 -tag a -tag b -tag c）。这时需要实现 flag.Val 接口。
例如实现可重复的字符串列表：
type stringList []string
func (s *stringList) Set(value string) error {
*s = append(*s, value)
return nil
}
func (s *stringList) String() string {
return strings.Join([]string(*s), ",")
}
func main() {
var tags stringList
flag.Var(&tags, "tag", "add tag (can be repeated)")
flag.Parse()
fmt.Printf("tags: %+v\n", tags) // -tag foo -tag bar → [foo bar]
}
-
Set()被每次匹配到该 flag 时调用，负责更新内部状态 -
String()仅用于-h输出展示，默认值显示，不参与解析 - 注意传指针给
flag.Var()，否则修改不会反映到原变量
flag.Parse() 会自动处理 -h / --help 并退出，无法拦截或自定义帮助文本
flag.Parse() 内置了对 -h 和 --help 的响应：打印 Usage 后直接调用 os.Exit(0)。这意味着你无法在 flag.Parse() 后加日志、清理或自定义帮助逻辑。
如果你需要：
- 输出 Markdown 格式帮助？→ 改用第三方库如
spf13/cobra - 在 help 前打印 banner 或版本？→ 无法绕过，只能放弃
flag自带 help - 区分
-h和非法参数？→flag.Parse()对两者都打印 Usage 并 exit(2)，无差别
替代方案：手动检查 os.Args 是否含 -h 或 --help，自行输出后调用 os.Exit(0)，再调用 flag.Parse() —— 但此时要禁用默认 help，用 flag.Usage = func(){}，否则会重复输出。
flag 无法原生支持子命令（如 git commit / git push）
flag 包本身没有子命令概念。像 mytool serve -port 8080 中的 serve 是普通位置参数，flag 不会将其当作命令分发点。
常见做法是：
- 先用
os.Args[1]判断子命令名，然后os.Args = os.Args[1:]截断，再初始化对应子命令的 flag 集合 - 每个子命令维护独立的
flag.FlagSet，避免全局 flag 冲突 - 注意
flag.CommandLine是全局默认集，子命令应使用私有flag.NewFlagSet(name, errorHandling)
例如：
func main() {
if len(os.Args) < 2 {
fmt.Fprintln(os.Stderr, "subcommand required")
os.Exit(1)
}
cmd := os.Args[1]
switch cmd {
case "serve":
serveCmd := flag.NewFlagSet("serve", flag.ContinueOnError)
port := serveCmd.Int("port", 8080, "server port")
serveCmd.Parse(os.Args[2:])
fmt.Printf("starting server on port %d\n", *port)
default:
fmt.Fprintf(os.Stderr, "unknown command: %s\n", cmd)
os.Exit(1)
}
}
这里关键点是：子命令的 Parse() 传入的是截断后的 os.Args[2:]，且错误处理设为 ContinueOnError，否则解析失败会直接 exit。
flag 本身足够轻量，但组合子命令、帮助生成、类型扩展时，很快会触达它的设计边界。真要长期维护 CLI 工具，尽早评估 cobra 或 urfave/cli 更实际。
