Go FlagSet 解析错误为什么没有打印完整用法

Go 的 flag.FlagSet 在解析失败时并不是“不会打印用法”。标准流程会先输出解析错误，再调用当前 FlagSet 的 Usage 函数。真正导致“用法不完整”的常见原因是自定义 Usage 覆盖了默认实现却没有调用 PrintDefaults，或者 SetOutput 把信息写进了你没有读取的缓冲区。

官方文档：https://pkg.go.dev/flag

先把“错误”和“用法”拆成两条链

NewFlagSet 的第二个参数只决定解析失败后的处理方式：ContinueOnError 返回错误，ExitOnError 退出进程，PanicOnError 触发 panic。它不负责生成参数列表。参数列表来自 Usage，默认实现内部才会调用 PrintDefaults。

因此，未知参数、缺少值或值类型不正确时，标准 FlagSet 的关系可以概括为：

自定义 Usage 时补回 PrintDefaults

最容易复现的问题是给 fs.Usage 赋了一个只打印标题的函数。赋值以后，默认 Usage 不会再替你打印所有 Flag；这时即使 Parse 触发了用法输出，读者也只能看到一行自定义提示。

package main

import (
	"flag"
	"fmt"
	"os"
)

func newFlags() *flag.FlagSet {
	fs := flag.NewFlagSet("backup", flag.ContinueOnError)
	fs.SetOutput(os.Stderr)
	fs.String("source", "./data", "`directory` to back up")
	fs.Bool("dry-run", false, "只打印计划，不写入目标目录")

	// 自定义标题后仍保留标准参数清单，避免 Usage 只剩一行提示。
	fs.Usage = func() {
		fmt.Fprintf(fs.Output(), "用法：%s [选项]\\n\\n", fs.Name())
		fs.PrintDefaults()
	}
	return fs
}

func main() {
	fs := newFlags()
	if err := fs.Parse(os.Args[1:]); err != nil {
		// ContinueOnError 会把控制权交还给调用方，由这里决定退出码。
		fmt.Fprintln(fs.Output(), "参数解析失败：", err)
		os.Exit(2)
	}
}

这里的关键不是把 Usage 写得更复杂，而是保留默认参数清单的职责。PrintDefaults 会按照 Flag 定义输出名称、类型提示、说明和必要的默认值；如果还需要示例，可以把示例文本放在它前后，但不要用一段固定字符串替代它。

SetOutput 要和读取位置保持一致

SetOutput 同时影响解析错误、默认 Usage 和 PrintDefaults 的写入目标。下面这种写法适合子命令、测试或需要把帮助内容交给上层渲染的场景：

func parseArgs(args []string, out io.Writer) error {
	fs := flag.NewFlagSet("report", flag.ContinueOnError)
	fs.SetOutput(out)
	fs.Usage = func() {
		fmt.Fprintln(fs.Output(), "report [选项]")
		// 用同一个 Writer 输出参数定义，调用方才能一次收齐信息。
		fs.PrintDefaults()
	}
	fs.String("format", "text", "输出格式")
	fs.Bool("verbose", false, "显示详细诊断")
	return fs.Parse(args)
}

如果 out 是 bytes.Buffer，就从这个 Buffer 读取；如果传入 os.Stderr，就从标准错误查看。不要一边把 FlagSet 绑定到 Buffer，一边只检查终端 stderr，这会制造“完全没打印”的假象。

ErrorHandling 只决定控制流，不负责补全帮助

命令行顶层入口可以用 flag.ExitOnError，让错误自动以非零状态结束；但子命令、测试和库式解析更适合 flag.ContinueOnError，这样上层可以区分未知参数、帮助请求和其他错误。无论选择哪一种，完整帮助都要由当前 Usage 负责。

还要注意 -h 与普通解析失败不同：如果没有显式定义这个 Flag，Parse 会调用 Usage 并返回 flag.ErrHelp。调用方可以把它当成正常帮助路径，不必把它记录成故障。

排查清单：五分钟定位用法缺失

1. 确认调用的是同一个 FlagSet：参数是不是定义在 fs，解析却用了全局 flag.Parse()。
2. 搜索 fs.Usage =：如果存在，检查其中是否调用 fs.PrintDefaults()。
3. 记录 fs.Output() 的实际目标，确认没有把内容写到未读取的 Buffer 或文件。
4. 检查 Parse 的返回值，尤其是 flag.ErrHelp 与普通错误的分支。
5. 最后再决定退出码；不要为了看到帮助而把 ExitOnError 改成 panic。

相关问题

为什么自定义 Usage 后只剩一行标题？

因为自定义函数替换了默认 Usage。把 fs.PrintDefaults() 加回自定义函数即可。

SetOutput(nil) 会关闭用法输出吗？

不会。传入 nil 时，FlagSet 会回退到标准错误；真正的问题通常是调用方查看了错误的 Writer。

ContinueOnError 会自动退出程序吗？

不会。它会返回解析错误，退出码和后续动作由调用方决定；Usage 仍可在解析失败时被调用。

如何让多个子命令各自拥有帮助信息？

为每个子命令创建独立的 FlagSet，分别设置 Name、Usage 和 Output，解析时只把该子命令的参数传给对应的 Parse。

记住这条边界就够了：ErrorHandling 管控制流，Usage 管帮助内容，SetOutput 管帮助去哪里。三者分别配置，FlagSet 的“错误后没有完整用法”就能稳定定位。