如何在Golang工程中引入Viper进行多环境配置文件统一管理

Viper 不自动多环境发现，需手动拼接配置名并调用 SetConfigName；嵌套结构体字段必须加 mapstructure tag；环境变量覆盖需 SetEnvKeyReplacer、SetEnvPrefix 和 AutomaticEnv 配合；Unmarshal 前必须先 ReadInConfig；测试需调用 Reset() 避免状态污染。

必须手动拼接配置文件名，Viper 不会自动根据 ENV 变量找 config.dev.yaml

SetConfigName 必须动态调用，不能写死

常见错误是把 viper.SetConfigName("config") 写成固定值，结果无论 ENV=prod 还是 ENV=dev，它都只去找 config.yaml。Viper 没有“自动多环境发现”能力。

• 正确做法：在 viper.ReadInConfig() 前，用环境变量拼出完整名字，例如 viper.SetConfigName("config." + os.Getenv("APP_ENV"))
• 确保 APP_ENV 已设置（推荐小写：dev/prod），且对应文件真实存在（如 ./config.dev.yaml）
• 如果配置路径不一致（比如 dev 文件在 ./configs/，prod 在 /etc/myapp/），需提前调用 viper.AddConfigPath("./configs") 或 viper.AddConfigPath("/etc/myapp/")
• 建议启动时加 os.Stat() 校验文件是否存在，避免静默失败

嵌套结构体字段必须带 mapstructure tag

YAML 里写 database: { host: "127.0.0.1", port: 3306 }，但 viper.GetString("database.host") 返回空？不是文件没读到，而是反射没匹配上字段。

• 顶层字段可省略 tag，但只要出现嵌套（哪怕只有一层），所有子字段都必须显式声明 mapstructure:"xxx"
• 例如：Host string `mapstructure:"host"`、Port int `mapstructure:"port"`，连字符字段如 max-connections 也得写成 `mapstructure:"max-connections"`
• 字段首字母必须大写（否则 Go 反射不可见），且 mapstructure 值要和 YAML 键完全一致（大小写、连字符、下划线都不能错）
• 调试时先跑 viper.AllKeys()，确认解析出的 key 列表是否含 database.host，再查结构体定义

环境变量覆盖需 SetEnvKeyReplacer + AutomaticEnv 配合

设了 APP_DATABASE_HOST=10.0.0.1，但 viper.GetString("database.host") 还是返回配置文件里的值？因为默认情况下，APP_DATABASE_HOST 不会映射到 database.host。

立即学习“go语言免费学习笔记（深入）”；

• 必须在 viper.ReadInConfig() 前调用：viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))（把点转下划线）
• 同时调用：viper.SetEnvPrefix("APP") 和 viper.AutomaticEnv()，三者缺一不可
• 顺序无关，但必须都在 ReadInConfig() 之前；否则环境变量注册失败，后续 Get* 调用完全无视它们
• 若只想覆盖个别敏感字段（如密码），用 viper.BindEnv("database.password", "APP_DATABASE_PASSWORD") 更精确

Unmarshal 前必须 ReadInConfig，且结构体字段不能写初始化值

结构体定义里写 Port int = 8080 是非法语法；更隐蔽的问题是：调了 viper.ReadInConfig() 后直接 viper.GetInt("server.port") 能拿到值，但 viper.Unmarshal(&cfg) 后 cfg.Server.Port 还是 0。

• viper.ReadInConfig() 只把内容加载进内部 map，不会自动赋值给结构体字段
• 必须紧接着调 viper.Unmarshal(&cfg) 才完成绑定；两个调用之间不能插其他逻辑（如改默认值）
• 结构体字段不能写初始化值（Go 语法不允许），默认值要用 viper.SetDefault("server.port", 8080) 设置
• 测试时务必调 viper.Reset()，否则单例状态残留会导致用例间污染

最容易被忽略的是：环境变量映射规则和 ReadInConfig() 的执行顺序——错一次，整个覆盖链就断了，而且不报错，只默默用文件里的旧值。