必须传指针（如&cfg），因viper.Unmarshal依赖反射修改可寻址值；传值或未初始化指针会导致字段静默为零值，且不报错。
传指针还是传值？viper.Unmarshal 静默失败的根源
传值给 viper.Unmarshal 会导致字段永远为零值，且不报错。这是因为 Unmarshal 内部需要修改原结构体字段，而 Go 的反射只能修改可寻址（addressable）的值。
- 必须传
&cfg，不能传cfg - 即使
cfg是指针类型（如*Config），也要确保它已初始化：cfg := &Config{}，否则reflect.ValueOf(cfg).Elem()会 panic - 常见错误写法：
viper.Unmarshal(Config{})→ 字段全为零，无提示
mapstructure 标签和 json 标签能混用吗？
不能随意混用。viper.Unmarshal 默认走的是 mapstructure 解码器，不是 json；json: 标签在部分场景下“碰巧”生效，但行为不可靠。
- 环境变量、YAML 文件、远程配置等多源合并后统一走
mapstructure，所以必须用mapstructure:"key" -
json:"key,omitempty"中的omitempty在mapstructure下无效，要用mapstructure:",omitempty" - 大小写敏感性不同：环境变量
DB_HOST能匹配mapstructure:"db_host"，但不保证匹配json:"db_host"
嵌套结构体字段没被赋值？检查导出性和 inline 声明
嵌套结构体字段未被解析，90% 是因为字段未导出或缺少 inline 显式声明——反射根本看不到小写字母开头的字段，也不会自动展开匿名字段。
- 子结构体字段也必须首字母大写：
DB struct { Host string `mapstructure:"host"` }，不能写host string - 若想扁平化映射（如 YAML 中
db_host: localhost直接映射到DB.Host），需加mapstructure:",inline"标签 - 匿名嵌入不等于自动 inline：
type Config struct { DB `mapstructure:",inline"` }才有效，光写DB不行
从 map[string]interface{} 手动反射赋值时最常 panic 的地方
reflect: call of reflect.Value.Interface on zero Value 这个 panic 几乎都发生在你对一个空值（missing 或 null）调用了 .Interface() —— 此时 reflect.Value 是 invalid 状态，不能直接取值。
立即学习“go语言免费学习笔记（深入）”；
- 每次取
data[key]后，先用val := reflect.ValueOf(v); if !val.IsValid() || val.Kind() == reflect.Invalid { continue }做校验 - 不要假设
map[string]interface{}里每个 key 都有非 nil 值；YAML 中port: null或缺失字段都会导致val.Kind() == reflect.Invalid - 设值前务必检查
fieldValue.CanSet()，尤其注意字段是否导出、目标结构体是否通过指针传入
