yaml.Unmarshal返回空或panic的根本原因是字段未导出（须首字母大写）或yaml标签错误（如空格、大小写不匹配、下划线键未显式标注），且必须传结构体指针；推荐用os.ReadFile+yaml.v3，动态结构用map[string]any。
直接用 gopkg.in/yaml.v3，别碰 v2 —— v2 已归档、不维护，v3 是当前唯一活跃分支，且修复了多个关键反序列化漏洞（比如嵌套 map 的类型推断错误、空字段覆盖行为）。
为什么 yaml.Unmarshal 总返回 nil 或 panic？
常见现象是结构体字段全为零值，或报错 cannot unmarshal !!str into struct。根本原因几乎都出在 struct tag 上：
-
yaml:"host"不能写成yaml: "host"（中间多空格就失效） - 字段必须是导出的（首字母大写），
host string不会被解析，得写Host string - 嵌套结构体如果没加
yaml:"xxx"tag，默认按字段名小写匹配，但 YAML 键名含下划线（如db_port）时会失败，必须显式标注DbPort int `yaml:"db_port"` - 切片字段若 YAML 中对应项为空（
roles: []或直接缺失），需加omitempty或确保结构体字段初始化为[]string{}，否则可能 panic
os.ReadFile vs yaml.NewDecoder 怎么选？
两者都能用，但场景不同：
- 用
os.ReadFile+yaml.Unmarshal：适合一次性读取完整文件，代码简洁，推荐绝大多数配置场景 - 用
yaml.NewDecoder：适合流式解析（比如从os.Stdin或网络连接读 YAML）、或需要控制解码过程（如跳过注释、限制嵌套深度）。注意它不自动关闭 reader，要自己defer file.Close() - 别混用：传给
yaml.Unmarshal的必须是[]byte，传*os.File会编译报错；传给yaml.NewDecoder的必须是io.Reader，传[]byte得先转bytes.NewReader(data)
如何安全处理 YAML 中的任意嵌套结构？
当配置格式不稳定、或需兼容多种版本 YAML（比如旧版用 redis，新版用 cache）时，硬编码 struct 容易崩。这时该用 map[string]any：
立即学习“go语言免费学习笔记（深入）”；
- 声明
var cfg map[string]any，直接yaml.Unmarshal(data, &cfg) - 访问嵌套值时用类型断言：比如
redis, ok := cfg["redis"].(map[string]any)，再取redis["port"].(int) - 注意：YAML 数字默认解析为
float64，整数也要断言成float64再转int，否则 panic - 性能略低（反射+类型检查），但换来的是配置变更零代码修改
最易被忽略的一点：YAML 文件路径错误时，os.ReadFile 报错信息里只说 no such file，但 Go 默认工作目录是 go run 所在目录，不是源码目录——调试时先 fmt.Println(os.Getwd()) 确认当前路径，再决定用相对路径还是 filepath.Join(filepath.Dir(runtime.Caller(0)), "config.yaml") 拼绝对路径。
