viper.SetDefault()必须在viper.ReadInConfig()和任何viper.Get*调用前设置，否则被忽略；默认值仅在键首次被访问且未被任何来源（环境变量、配置文件等）设置时生效，支持嵌套键和复杂类型，优先级为环境变量>配置文件>默认值。
viper.SetDefault() 必须在 ReadInConfig() 之前调用
默认值不会“自动兜底”已加载的配置，Viper 的默认值机制是 lazy 的：只在某个键首次被 viper.Get* 访问、且当前内存中无该键值时，才查默认值表。一旦 viper.ReadInConfig() 执行完毕，所有键的状态就被固化——哪怕配置文件里根本没写 timeout，Viper 也认为“这个键明确不存在”，后续 viper.GetInt("timeout") 就不会触发默认值逻辑。
常见错误现象：
- 先
viper.ReadInConfig()，再viper.SetDefault("timeout", 30)→ 默认值完全无效 - 配置文件存在但字段缺失（如 YAML 里没写
log.level），却期望它自动 fallback 到默认值 → 不会生效，除非默认值设置在读取前
正确顺序必须是：
viper.SetDefault("db.host", "localhost")viper.SetDefault("features", []string{"auth"})viper.AddConfigPath("./configs")viper.SetConfigName("app")viper.ReadInConfig()
嵌套结构体默认值要按 mapstructure 路径设
Viper 不解析 Go struct 字段名或 tag，它只认扁平化的键路径（如 db.host）。如果你用 viper.Unmarshal(&cfg) 解析到一个结构体，而该结构体字段带 mapstructure:"host"，那对应默认值就必须写成 viper.SetDefault("db.host", "127.0.0.1")，而不是 "DB.Host" 或 "db.Host"。
立即学习“go语言免费学习笔记（深入）”；
容易踩的坑：
- 结构体嵌套两层以上（如
cache.redis.url），默认值路径漏掉中间点，比如写成"cache.url"→ 解析失败且静默跳过 - 字段 tag 写错，比如
mapstructure:"redis_url"，但默认值设的是"cache.redis.url"→ 键不匹配，字段保持零值 - 使用
viper.Unmarshal()时，结构体字段未导出（小写开头）→ Viper 无法写入，也不报错，字段永远为空
环境变量会直接覆盖默认值，空字符串也算
viper.AutomaticEnv() 开启后，只要环境变量存在（哪怕值为空），就会跳过默认值。优先级永远是：环境变量 > 配置文件 > 默认值。
典型问题场景：
-
viper.SetEnvPrefix("APP")+os.Setenv("APP_LOG_LEVEL", "")→viper.GetString("log.level")返回空字符串，不是默认的"info" - 想让空环境变量退回到默认值？必须手动判断：
if viper.GetString("log.level") == "" { ... } - 需要精确控制映射关系时，别依赖
AutomaticEnv()的自动转换（.和-全转_），改用viper.BindEnv("log.level", "LOG_LEVEL")
配置文件未找到不是因为路径错，而是 Viper 没去查
"Config File Not Found" 错误的根源不是文件丢了，而是 Viper 根本没扫描你放配置的目录。它默认只在当前工作目录（os.Getwd()）下找，且不递归子目录、不向上遍历父目录。
必须显式告诉它去哪儿找：
-
viper.AddConfigPath("./configs")—— 支持多次调用，按添加顺序查找 -
viper.SetConfigName("app")—— 对应文件名，如app.yaml，不能写成"config"如果实际是app.yaml -
viper.SetConfigType("yaml")—— 显式指定类型，避免因无扩展名或扩展名不标准导致识别失败 - 运行时工作目录可能和 IDE 启动目录不一致（尤其
go test或容器中），建议启动时加fmt.Println("wd:", os.Getwd())确认
最稳妥的根目录方案：viper.AddConfigPath(".") + viper.SetConfigName("config")，并确保执行命令在项目根下运行。
