yaml.Unmarshal失败主因是结构体字段未导出或yaml标签错误：字段须首字母大写，标签大小写及下划线须与YAML键严格匹配，且必须传结构体指针、检查文件读取错误、使用gopkg.in/yaml.v3。
yaml.Unmarshal 失败不是 YAML 语法问题，八成是结构体字段没导出或 yaml: 标签写错了。别急着调格式，先看字段名和 tag。
结构体字段必须首字母大写 + 显式 yaml:"key" 标签
Go 反射无法写入小写字母开头的字段，yaml.Unmarshal 会直接跳过，不报错也不赋值——这是最常被忽略的静默失败原因。
- 错误写法：
port int `yaml:"port"`→ 字段port未导出，永远为0 - 正确写法：
Port int `yaml:"port"`→ 首字母大写，且yaml:"port"与 YAML 中的键完全一致（大小写、下划线） - YAML 键含下划线时（如
db_host），必须显式标注：DBHost string `yaml:"db_host"`，不能依赖自动小写转换 - 嵌套结构体同理：外层字段也要导出 + 加 tag，例如
Server ServerConfig `yaml:"server"`
os.ReadFile 后必须传指针给 yaml.Unmarshal
传值（config）不会修改原变量；传指针（&config）才能真正写入。漏掉 & 是编译能过但运行无效的典型坑。
- 正确：
err := yaml.Unmarshal(data, &config) - 错误：
err := yaml.Unmarshal(data, config)→ 编译失败（类型不匹配）或静默失败（若config是指针类型但你误传了值） - 读文件前务必检查错误：
data, err := os.ReadFile("config.yaml"); if err != nil { log.Fatal(err) }，否则空data会导致Unmarshal返回模糊错误 - YAML 文件路径默认基于当前工作目录（
os.Getwd()），不是源文件所在目录；打包进二进制时，得用embed.FS替代os.ReadFile
用 map[string]any 解析动态结构更安全
当配置格式可能变化、或需兼容多个版本（比如旧版用 redis，新版用 cache），硬编码结构体会频繁 panic。此时放弃结构体，改用 map[string]any 更鲁棒。
- 声明：
var cfg map[string]any，然后yaml.Unmarshal(data, &cfg) - 访问嵌套值需多层类型断言：
if redis, ok := cfg["redis"].(map[string]any); ok { port := int(redis["port"].(float64)) } - 注意：YAML 数字一律解析为
float64，即使写的是port: 8080，也得先转float64再转int - 性能略低，但换来的是配置变更零代码修改，适合配置项不稳定或由外部提供 YAML 的场景
v3 版本必须用 gopkg.in/yaml.v3，别碰 v2
gopkg.in/yaml.v2 已归档、无维护，存在反序列化漏洞（如嵌套 map 类型推断错误），且对空字段、null 值处理不一致。v3 是唯一活跃分支，修复了关键问题。
立即学习“go语言免费学习笔记（深入）”；
- 安装：
go get gopkg.in/yaml.v3，导入路径也必须是gopkg.in/yaml.v3 - v2 的
ioutil.ReadFile已废弃，v3 场景下统一用os.ReadFile（Go 1.16+） - v2 的 struct tag 写法（如
yaml:"port,omitempty"）在 v3 中行为有差异，omitempty在 v3 中仅影响序列化，不影响反序列化逻辑 - 如果你用 Viper，它底层默认走
mapstructure解码器，yaml:标签不生效，得换mapstructure:标签
Unmarshal 失败有九次栽在这上面。别信“应该能自动匹配”，YAML 键名和 Go 字段名之间没有魔法映射，全靠你手写对。 
