viper不能直接import就用，因其默认全局单例依赖初始化顺序：必须在main开头显式调用setconfigname、addconfigpath、readinconfig等完成加载，否则其他包提前读取会返回零值且无提示；跨包应导出自定义实例并测试时重置。
viper 不是开箱即用的“全局单例”，必须显式初始化并导出实例，否则多包引用时会读不到配置或覆盖彼此状态。
为什么不能直接 import "github.com/spf13/viper" 就用？
viper 默认使用一个全局实例，但它的行为依赖于调用顺序和初始化时机。如果 main 包还没调用 viper.ReadInConfig()，其他包提前调用 viper.GetString("xxx") 就会返回零值（比如空字符串、0），且无任何错误提示。
常见错误现象：结构体字段绑定后仍是零值；viper.ConfigFileUsed() 返回空字符串；viper.AllKeys() 为空。
- 所有配置加载逻辑（
SetConfigName、AddConfigPath、ReadInConfig）必须在程序启动早期、任何业务代码读取配置前完成 - 推荐封装为
config.Load()函数，在main()开头立即调用 - 若需跨包访问，导出的是自定义实例（如
var Cfg *viper.Viper），而非直接用全局viper - 测试中必须调用
viper.Reset()，否则前一个测试残留的配置会影响下一个
如何正确加载 config.yaml / config.json / config.toml？
文件扩展名决定格式识别，但路径和命名规则必须严格。Viper 不会自动扫描目录下所有 config.* 文件——它只找你指定的 SetConfigName + 第一个命中路径下的匹配文件。
- 设
viper.SetConfigName("config")（不带后缀），再调viper.AddConfigPath("./configs")，它才会去找./configs/config.yaml - 如果文件叫
config（无扩展名），必须手动viper.SetConfigType("yaml")，否则报错Unsupported Config Type "" - 多个同名文件共存（
config.yaml和config.json）时，Viper 按AddConfigPath添加顺序查找，先找到就停，不会合并 - 建议加一层存在性校验：
if _, err := os.Stat(viper.ConfigFileUsed()); os.IsNotExist(err) { log.Fatal("config file not found") }
怎么把配置安全地绑定到 Go 结构体？
viper.Unmarshal(&cfg) 不是魔法，它依赖 ReadInConfig() 已成功执行，且结构体字段 tag 必须与配置 key 完全一致（包括大小写、下划线）。
- 字段必须首字母大写（导出），例如
Port int `yaml:"port"`，小写port int绑定失败 - 嵌套结构体也需 tag，如
DB Database `yaml:"database"`，且Database内部字段也要带yaml:标签 - 别在结构体里写
Timeout int = 30—— Go 不允许字段初始化，应改用viper.SetDefault("server.timeout", 30) - 若配置键含下划线（
db_user），要么结构体字段也用db_user string `yaml:"db_user"`，要么提前调viper.SetEnvKeyReplacer(strings.NewReplacer("_", "."))
环境变量和命令行参数怎么真正生效？
viper.AutomaticEnv() 和 viper.BindEnv() 必须在 ReadInConfig() 之前调用，否则注册无效。它们不修改文件加载逻辑，只影响后续 GetString() 的取值来源。
- 想让
APP_SERVER_PORT=8080覆盖配置文件里的server.port，得先viper.SetEnvPrefix("APP")，再viper.AutomaticEnv()，最后ReadInConfig() -
viper.BindEnv("server.port", "APP_SERVER_PORT")中第二个参数必须与真实环境变量名完全一致（大小写敏感） - 环境变量值始终是字符串，
viper.GetInt("server.port")才尝试转换；设成APP_SERVER_PORT="8080"（带引号）会导致返回 0 - 多环境文件切换靠手动拼接：
env := os.Getenv("GO_ENV"); if env == "" { env = "dev" }; viper.SetConfigName("config." + env)
viper.Reset() 或错放一行 AutomaticEnv()，都会导致配置静默失效，排查起来比 panic 还难。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
