Go语言实现简单命令行工具_Go CLI项目入门教程

Go命令行工具用flag包即可高效开发，但需注意：必须调用flag.Parse()才能生效；子命令宜用独立FlagSet；String与StringVar按意图选用；禁用CGO并加-ldflags="-s -w"可大幅减小体积。

Go 语言写命令行工具，不需要第三方库也能做得干净利落；flag 包足够支撑大多数简单 CLI 场景，但直接上手容易踩参数绑定、错误处理和子命令模拟的坑。

用 flag 解析基础参数时，别漏掉 flag.Parse()

很多新手写完 flag.String 或 flag.Bool 就直接读变量，结果值全是零值——因为没调用 flag.Parse()。它不只是“解析”，还负责截断 os.Args、触发 usage 打印、处理 -h/--help（如果设置了）。

常见错误现象：flag.String("output", "", "output file") 返回的指针始终指向空字符串。

• 必须在所有 flag.Xxx()

  

  调用之后、首次读取 flag 值之前执行 flag.Parse()
• 若需保留原始 os.Args[1:]（比如做子命令分发），应在 flag.Parse() 前保存副本
• flag.Usage 是函数变量，可自定义 help 输出，但注意它不自动退出，需手动调用 os.Exit(0)

处理多个子命令（如 mytool serve 和 mytool migrate）不用立刻上 spf13/cobra

小工具初期真没必要引入重量级框架。os.Args 手动切分 + 简单 switch 就够用，清晰且无隐藏行为。

使用场景：工具刚起步，只有 2–4 个功能入口，每个子命令参数结构简单。

• 先检查 len(os.Args) > 1，再取 os.Args[1] 判断子命令名
• 每个子命令各自初始化独立的 flag.FlagSet，避免参数冲突（例如 serve -port 和 migrate -dry-run 共存）
• 用 flag.NewFlagSet(cmdName, flag.ContinueOnError) 创建子集，错误时不退出主流程
• 子命令的 flag.Parse() 应传入对应子集的 os.Args[2:]，不是全局 os.Args

flag.StringVar 和 flag.String 的选择影响内存与可读性

二者都返回 *string，但初始化方式不同，容易混淆何时该用哪个。

性能 / 兼容性影响：无实质差异；关键在代码意图表达是否清晰。

• flag.String("name", "default", "desc") —— 适合默认值固定、无需运行时计算的场景，返回指针，生命周期由 flag 包管理
• flag.StringVar(&nameVar, "name", "default", "desc") —— 当变量已在作用域中声明（比如 struct 字段或局部变量），且你希望复用该变量地址，避免解引用操作
• 误用 StringVar 指向未初始化的 nil 指针会 panic；确保目标变量已声明（哪怕只是 var name string）

编译后二进制体积大？关掉 CGO 和调试信息就行

默认 go build 生成的 CLI 可执行文件常有 5–10MB，对分发不友好，其实绝大多数 CLI 完全不需要 CGO。

原因：Go 默认启用 CGO（用于调用 C 库），即使没写 C 代码，某些标准库（如 net）也会链接系统 DNS 解析逻辑，导致依赖 glibc 或 musl。

• 加 CGO_ENABLED=0 编译：CGO_ENABLED=0 go build -ldflags="-s -w" -o mytool .
• -s 去除符号表，-w 去除 DWARF 调试信息，两者合用通常能压到 3–4MB 以下
• 纯静态链接后，可直接扔到 Alpine 容器或任意 Linux 发行版运行，无 libc 依赖
• 注意：CGO_ENABLED=0 下 net.Resolver 会退化为纯 Go 实现（不查 /etc/resolv.conf），多数 CLI 场景无感

真正麻烦的是子命令间共享配置逻辑和 flag 复用——这时候才值得考虑 urfave/cli 或 cobra，而不是一开始就被“标准做法”带偏。