根本原因是结构体字段未导出（首字母小写）或yaml键名与字段标签不匹配；需确保所有层级字段及类型名均首字母大写，并显式使用yaml:"key"标签精确映射。
为什么 struct 字段解析 YAML 后总是空值
Go 的 yaml.Unmarshal 只能给导出（首字母大写）字段赋值，非导出字段（小写开头）会被忽略，即使 YAML 里有对应 key，结构体里也始终是零值。这不是 bug，是 Go 反射机制的硬性限制——reflect.Value.CanSet() 对非导出字段返回 false。
常见现象：yaml.Unmarshal 不报错，但解析后字段全为 ""、0 或 nil；用 yaml.Marshal 再序列化时，那些字段也不出现。
- 必须确保 struct 字段首字母大写（如
Name，而非name） - 字段需有公开的 getter/setter 才能被反射读写，Go 中即靠大小写控制
- 如果字段类型是自定义非导出类型（如
type userID int），该类型本身也需导出，否则仍无法设值
如何正确声明 struct 并绑定 YAML 字段名
光导出字段还不够，YAML key 和 struct 字段名往往不一致，得靠 struct tag 显式映射。默认行为是按字段名（驼峰转小写下划线）匹配，但不可靠，建议显式写死。
示例：
type Config struct {
Port int `yaml:"port"`
DBAddr string `yaml:"db_addr"`
IsDebug bool `yaml:"is_debug"`
Timeout int `yaml:"timeout_ms"` // 注意单位说明也进了 key
}
- tag 值区分大小写，
yaml:"Port"和yaml:"port"是不同 key - 加
omitempty可跳过零值字段（仅影响Marshal，不影响Unmarshal） - 若 YAML 中存在字段在 struct 中没有对应项，
Unmarshal默认静默忽略；加yaml:",inline"可嵌入未声明字段到 map[string]interface{}
遇到嵌套结构或 map 类型怎么处理
嵌套 struct 同样遵循导出规则：所有层级的字段都必须导出，且每层 struct 类型名也要首字母大写。map 的 key 必须是可比较类型（如 string、int），value 类型若为 struct，其字段也需导出。
错误写法（内层 server 非导出）：
type Config struct {
Server server `yaml:"server"` // ❌ server 小写，无法解析
}
type server struct { // ❌ 类型名小写
Host string `yaml:"host"`
}
正确写法：
type Config struct {
Server Server `yaml:"server"` // ✅ 大写类型名 + 大写字段名
}
type Server struct { // ✅ 导出类型
Host string `yaml:"host"`
Port int `yaml:"port"`
}
- map[string]struct{} 中的 struct，字段也必须导出，否则 map 解析后 struct 字段为空
- 若想保留原始 YAML 的 key 名（含特殊字符或数字开头），只能用
map[interface{}]interface{}+ 手动类型断言，但失去静态类型检查
调试时怎么快速定位字段没被赋值的原因
别只看 err == nil 就以为成功了。实际解析失败但无 error 的情况很常见（比如字段未导出、类型不匹配、tag 写错）。最直接的办法是反向验证：
- 先用
yaml.Marshal把你的 struct 序列化成 YAML，看字段是否出现在输出中；没出现 = 字段未导出或 tag 设为omitempty且值为零 - 打印
reflect.TypeOf(v).NumField()确认反射能看到几个字段，再逐个查Field(i).IsExported() - 把 YAML 文件用在线 YAML 转 JSON 工具格式化后人工比对 key 名和 struct tag 是否完全一致（注意空格、下划线、大小写）
最容易被忽略的是：struct 类型名本身没导出，或者嵌套字段的类型定义在另一个包里且未导出——这种情况下，哪怕字段名大写也没用，反射根本进不去那个类型内部。
