Go flag.Parse 为什么不能在 init 中提前调用

我遇到过一种很容易误判的 Go 启动问题：同样的 -config app.yaml 参数，放在 main 里解析能生效，挪到 init 后却变成未知参数，或者业务仍然拿到默认值。原因不是 flag.Parse 不能写进 init，而是它承担了“读取并结束一次参数解析”的动作；调用时必须已经完成所有 flag 注册。

Go flag.Parse 的问题不在语法，而在初始化边界

Go 规范规定，包级变量初始化和 init 会在 main 调用前完成；导入包也会先初始化。与此同时，flag 文档要求 Parse 在所有 flag 定义完成后调用。把这两条放在一起看，init 只是“可能太早”，并不是一个可靠的解析入口。

典型风险是一个 init 先执行了 flag.Parse()，另一个稍后执行的 init 才调用 flag.StringVar 注册参数。此时后注册的参数没有机会参与前一次解析；如果命令行里已经带了它，默认的 ExitOnError 还可能在进入 main 前直接结束进程。

先复现：把解析和注册拆成两个阶段

下面的代码故意把解析放进初始化函数，再在另一个初始化函数里注册参数。它说明的不是某个文件名一定先后，而是：只要 Parse 早于注册，参数就不在解析器当时看到的集合里。

package main

import (
	"flag"
	"fmt"
)

var mode string

func init() {
	// 错误示例：解析发生在后续 flag 注册之前。
	flag.Parse()
}

func init() {
	// 这个参数注册得太晚，前一次 Parse 不会重新读取命令行。
	flag.StringVar(&mode, "mode", "safe", "运行模式")
}

func main() {
	// 这里已经无法补救一次过早的解析。
	fmt.Println("mode:", mode)
}

修复默认命令行参数时，把所有定义留在包初始化阶段，把唯一一次解析放到 main 的入口附近：

package main

import (
	"flag"
	"fmt"
)

var mode = flag.String("mode", "safe", "运行模式")

func main() {
	// 所有 flag 已完成定义，现在读取 os.Args[1:]。
	flag.Parse()
	// Parse 后再访问值和位置参数，边界最清楚。
	fmt.Println("mode:", *mode)
	fmt.Println("args:", flag.Args())
}

正确修复：让 main 或 FlagSet 持有解析边界

如果程序有子命令、库代码或测试，不要让导入包偷偷解析全局 os.Args。创建独立 FlagSet，传入明确参数，并选择 ContinueOnError，调用方就能决定如何展示错误、是否继续或如何测试。

func parseArgs(args []string) (string, []string, error) {
	fs := flag.NewFlagSet("worker", flag.ContinueOnError)
	fs.SetOutput(io.Discard) // 测试或上层命令自行决定错误输出位置。
	mode := fs.String("mode", "safe", "运行模式")
	if err := fs.Parse(args); err != nil {
		// 返回错误而不是在 init 阶段退出整个进程。
		return "", nil, err
	}
	return *mode, fs.Args(), nil // 位置参数与命名 flag 分开交给调用方。
}

这段示例需要额外导入 io。生产代码里还要明确重复调用 Parse 的责任：同一个 FlagSet 通常只解析一次；若是不同子命令，就为每个子命令创建自己的 FlagSet，而不是复用已经解析过的全局集合。

复查清单：判断修复是否真的完成

• 搜索全项目的 flag.Parse()，确认没有库包或 init 偷偷提前解析。
• 用已注册参数、未知参数和位置参数各跑一次，确认未知参数走预期的错误分支。
• 检查 --mode fast input.txt 这类输入：命名 flag 进入变量，input.txt 出现在 Args()，并留意解析会在第一个非 flag 参数处停止。

常见问题

把 flag 定义写在 init 里是不是也错？

不一定。定义可以放在 init，但必须保证它发生在 Parse 之前；为了降低跨文件和跨包的时序耦合，声明式定义或集中注册更稳妥。

init 里没有参数时为什么看起来能用？

因为当前代码恰好在 Parse 前完成了全部注册，或命令行没有触发未知参数。它只是偶然满足前置条件，新增一个初始化函数后仍可能失效。

什么时候应该使用 FlagSet？

需要子命令、可测试解析、库与 CLI 解耦，或希望把错误交给上层处理时，使用显式 FlagSet。核心原则是让解析边界可见、可传入、可返回。