viper 是 Go 最实用配置库，支持多格式、多来源、热重载及环境变量自动映射；需注意加载顺序（AutomaticEnv 必须在 ReadInConfig 前）、结构体导出字段要求及优先使用 Get+类型断言而非全量 Unmarshal。

Go 语言没有官方配置库，但社区方案成熟稳定，viper 是目前最实用、覆盖场景最广的选择——前提是正确使用它，否则反而引入隐式行为和加载顺序陷阱。

为什么 viper 比手写 json.Unmarshal 更可靠

手动解析配置需要自己处理文件读取、格式判断、嵌套结构映射、环境变量覆盖、默认值 fallback 等逻辑，容易遗漏边界情况。而 viper 将这些封装为声明式调用，且天然支持多格式（JSON、YAML、TOML、ENV）、多来源（文件、命令行、环境变量、远程 etcd）。

• 自动监听 ConfigFile 变更并热重载（需显式启用 viper.WatchConfig()）
• 环境变量名可自动转为小写+下划线（如 DB_HOST → db.host），无需手动映射
• 支持 viper.SetDefault("log.level", "info") 统一管理默认值，避免结构体字段零值误用

viper 加载顺序与常见覆盖错误

配置项的最终值取决于加载顺序：命令行参数 > 环境变量 > 配置文件 > 默认值。但很多人忽略一点——viper.ReadInConfig() 必须在 viper.AutomaticEnv() 之后调用，否则环境变量不会参与覆盖。

• 错误写法：viper.ReadInConfig() 在前，viper.AutomaticEnv() 在后 → 环境变量完全不生效
• 正确顺序：先 viper.SetConfigName("config")、viper.AddConfigPath("./conf")，再 viper.AutomaticEnv()，最后 viper.ReadInConfig()
• 若用 viper.BindEnv("http.port", "HTTP_PORT") 显式绑定，该键将优先于 AutomaticEnv 的自动推导

结构体绑定时的类型安全陷阱

viper.Unmarshal(&cfg) 看似方便，但 Go 的反射机制对字段标签、嵌套结构、零值处理并不透明，容易导致静默失败或类型错配。

• 必须确保结构体字段是导出的（首字母大写），否则 Unmarshal 不会赋值
• 嵌套结构需用 viper.Sub("database") 单独解包，或用 mapstructure.DecodeHook 处理自定义类型（如 time.Duration）
• 推荐组合用法：viper.Get("server.port") + 类型断言，比全量 Unmarshal 更易定位哪一项解析失败
• 示例：port := viper.GetInt("server.port") // 自动转 int，失败返回 0；用 GetInt64 更安全

真正难的不是读取配置，而是让不同环境（dev/staging/prod）的配置差异清晰可见、不可绕过。建议把环境标识（如 viper.GetString("env")）作为加载路径的一部分：viper.AddConfigPath(fmt.Sprint