yaml.Unmarshal 返回零值主因是结构体字段未导出或 yaml 标签错误：字段须首字母大写，标签大小写须与 YAML 键严格匹配，且需传指针、检查错误、避免在 Unmarshal 中处理业务逻辑。
yaml.Unmarshal 返回零值？八成是结构体字段没导出，或者 yaml: 标签写错了。别急着换库，先检查这几点。
结构体字段必须首字母大写，否则静默丢弃
Go 的反射机制只能访问导出字段（首字母大写）。小写字段如 port、timeout 在解析时完全不参与，也不报错——直接设为零值。
- 错误写法：
type Config { port int `yaml:"port"` }→port值永远是0 - 正确写法：
type Config { Port int `yaml:"port"` }，靠yaml:"port"映射 YAML 中的小写键 - 嵌套结构体同理：子结构体字段也必须导出，不能只导出顶层字段
-
yaml:标签值严格区分大小写：yaml:"Port"对应 YAML 里的Port: 8080，不是port: 8080
读文件必须用 os.ReadFile，且检查 err 和传指针
ioutil.ReadFile 已在 Go 1.16 正式弃用，继续用会触发编译警告；os.ReadFile 是官方推荐替代。
- ❌ 已弃用：
yamlFile, err := ioutil.ReadFile("config.yaml") - ✅ 推荐写法：
yamlFile, err := os.ReadFile("config.yaml") - 必须检查
err：路径不存在、权限不足、BOM 或不可见字符都会导致后续yaml.Unmarshal失败 - 传给
yaml.Unmarshal的目标必须是指针，比如&cfg，不是cfg - 建议读取后先打印前 200 字节：
fmt.Printf("%q\n", yamlFile[:min(200, len(yamlFile))])，排查 BOM 或控制字符干扰
动态键名（如 production、V2）不能硬套结构体
当 YAML 顶层是运行期才确定的 key（例如环境名、版本号），固定结构体必然失败。用 map[string]interface{} 又容易 panic——因为 v3 默认解析出的是 map[string]any，类型断言 v["V1"].(map[string]interface{}) 会崩。
立即学习“go语言免费学习笔记（深入）”；
- 推荐方案：为结构体实现
UnmarshalYAML接口，在方法内分步解析 - 先提取已知字段（如
skip-header-validation），再把剩余部分解析为map[string]MajorVersion - 顶层接收动态 key 时，直接用
map[string]Environment，别试图塞进单个Environment实例 - 临时调试可用
yaml.Node手动遍历整棵树，但生产环境不推荐
默认值和业务逻辑必须放在 Unmarshal 之后
yaml.Unmarshal 的唯一职责是“把 YAML 字节准确转成 Go 值”。字段联动、环境适配、默认填充等都属于业务逻辑，应该放在解析之后、使用之前统一处理。
- 例如：根据
env: "prod"自动设log_level: "warn"，不要写进UnmarshalYAML方法 - 避免在
UnmarshalYAML中做校验或转换，否则难以复用、难测试、易耦合 - 关键字段缺失时，应在解析后显式校验（如
if cfg.Port == 0），而不是依赖解析阶段报错
最常被忽略的其实是字段导出规则和标签大小写匹配——这两点不出错，90% 的解析失败都能当场定位。动态键和默认值逻辑则最容易在后期维护中被塞进解析流程，埋下隐性耦合。
