Go flag.FlagSet 遇到 -- 后怎么正确解析位置参数

如果一个 Go 命令既要接收自己的选项，又要把带连字符的文件名或子命令参数继续传给下游，最容易误判的地方就是 --。在 flag.FlagSet 中，它是“停止选项解析”的终止符；它后面的参数不会再被当成 flag，而会原样留在 FlagSet.Args() 中。

官方地址：https://pkg.go.dev/flag#FlagSet.Parse

还原参数被吞掉的现场

假设程序负责读取自己的 -output 和 -verbose，同时把后半段参数交给另一个处理器：

tool -verbose -output result.txt -- -draft.md --keep

这里的第一个 -- 不是要传给下游的业务参数，而是告诉 FlagSet：到此为止，前面的选项解析结束。解析结果可以理解为：

因此，问题通常不是 FlagSet 把参数删除了，而是代码只查看了已经绑定的 flag 变量，没有继续读取剩余参数。

先确认 FlagSet 的停止规则

官方 flag 包允许一个或两个短横线写在选项名前，例如 -output 与 --output 等价。但这和单独出现的 -- 不是一回事：单独的 -- 是终止符，表示后面的内容不再参与选项识别。

还有一个经常被忽略的边界：即使没有写 --，解析也会在第一个非 flag 参数前停止。比如输入 -output result.txt input.txt -verbose 时，input.txt 会成为剩余参数的起点，后面的 -verbose 也不会重新被识别成选项。为了让所有程序选项都生效，通常把选项放在位置参数之前；为了透传带连字符的内容，则显式使用 --。

单独的 - 也是非 flag 参数，它可以代表标准输入等业务约定，不能把它当成终止符替代品。

用最小程序读取剩余参数

下面的示例使用独立的 FlagSet，避免修改全局 flag 集合。传给 Parse 的切片不包含命令名；解析完成后，程序再从同一个集合读取剩余参数。

package main

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

func main() {
	// 独立的 FlagSet 便于子命令或包装器单独管理自己的选项。
	fs := flag.NewFlagSet("tool", flag.ContinueOnError)
	output := fs.String("output", "stdout", "输出目标")
	verbose := fs.Bool("verbose", false, "是否输出详细信息")

	// Parse 的输入不包含命令名；错误要交给调用方决定如何处理。
	if err := fs.Parse(os.Args[1:]); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(2)
	}

	// Args 返回 -- 后的参数切片，保留每个值的原始顺序和连字符。
	fmt.Printf("output=%s verbose=%t args=%q\n", *output, *verbose, fs.Args())
	if fs.NArg() > 0 {
		// Arg(0) 只读取第一个剩余参数，适合约定首项为输入文件的场景。
		fmt.Printf("first positional=%q\n", fs.Arg(0))
	}
}

当输入为 tool -verbose -output result.txt -- -draft.md --keep 时，output 是 result.txt，verbose 为 true，而 fs.Args() 只包含 -draft.md 和 --keep。如果不需要切片，可以使用 Arg(i) 按索引访问，并用 NArg() 先判断索引是否存在。

把 -- 放在参数透传边界

如果外层程序只是做一层包装，常见需求是“外层消费自己的选项，内层接收其余参数”。这时可以把 fs.Args() 作为下游调用的参数源，而不是再次扫描 os.Args：

func parseWrapper(argv []string) (string, bool, []string, error) {
	// 外层只声明自己拥有的参数，避免误认下游参数。
	fs := flag.NewFlagSet("wrapper", flag.ContinueOnError)
	config := fs.String("config", "app.yaml", "外层配置文件")
	dryRun := fs.Bool("dry-run", false, "只预览不执行")

	// -- 后的参数会进入 fs.Args，适合原样交给下游命令或解析器。
	if err := fs.Parse(argv); err != nil {
		return "", false, nil, err
	}
	forwarded := append([]string(nil), fs.Args()...)
	return *config, *dryRun, forwarded, nil
}

调用时可以写成 wrapper -config release.yaml -- -input data.csv --mode strict。外层只消费 -config，下游收到的切片是 []string{"-input", "data.csv", "--mode", "strict"}。复制一份切片的目的，是让返回值不依赖 FlagSet 内部持有的底层数组，便于后续代码保存或异步使用。

按边界场景复查结果

排查“位置参数没有拿到”时，可以按下面的顺序对照，不需要重新设计一套解析器：

尤其要注意，-- 只负责切断当前 FlagSet 的解析，它不会替下游解释参数。下游如果也使用 Go 的 FlagSet，可以把 fs.Args() 作为它的输入；如果下游有自己的语法，则由下游自行决定如何理解这些字符串。

常见的几个追问

Args() 会包含终止符 -- 吗？

不会。-- 是 flag 包用来停止解析的控制符，剩余参数从它后面的第一个值开始。

能不能先解析位置参数，再继续解析后面的 flag？

不能依赖标准 FlagSet.Parse 自动回头解析。它遇到首个非 flag 参数或终止符后就停止；如果业务语法需要两段选项，应明确拆成多个 FlagSet 或由上层先划分边界。

为什么 -file 会被当成未知选项？

如果它出现在 -- 之前，它仍处在当前 FlagSet 的选项区。把它作为文件名传递时，应放到 -- 后面，或者把文件名设计成不以连字符开头。

归根结底，FlagSet 的关键不是“把所有参数都解析成 flag”，而是把选项区与位置参数区划出清晰边界：自己的选项放在前面，需要原样传递的内容放在 -- 后面，最后统一从 Args()、Arg(i) 或 NArg() 读取。