根本原因是结构体字段未导出或YAML键名与字段标签不匹配；需确保字段首字母大写、正确使用yaml:"key"标签，并传入结构体指针，同时注意embed.FS路径绑定和错误检查。
yaml.Unmarshal 为什么总是返回空结构体？
根本原因通常是结构体字段没导出，或者 YAML 键名和字段标签不匹配。Go 的 yaml.Unmarshal 只能设置已导出（首字母大写）的字段，且默认按字段名（或 yaml 标签）映射键名。
- 确保结构体字段首字母大写，例如
Port而不是port - 显式用
yamlstruct tag 对齐 YAML 键，比如Port int `yaml:"port"`，否则会按 Go 字段名（Port→port）小写自动转换，但不保险 - 如果 YAML 里是
redis_url，别写成RedisUrl却漏掉 tag —— 默认会找redisurl，而不是redis_url - 嵌套结构体也要逐层导出，内层字段同样要大写 + 合理 tag
读取文件时 panic: unmarshal errors 或 nil pointer dereference
常见于没检查 ioutil.ReadFile（Go 1.16+ 改用 os.ReadFile）返回的 error，或直接对未初始化的结构体指针解码。
- 必须先检查文件读取错误：
data, err := os.ReadFile("config.yaml"); if err != nil { ... } - 传给
yaml.Unmarshal的目标必须是指针，比如&cfg，不是cfg - 如果结构体里有 map 或 slice 字段，不用手动 make，
yaml包会自动初始化；但若字段是自定义类型且没实现 UnmarshalYAML，就会 panic - 注意：YAML 中的
null值会让对应字段保持零值，不会 panic，但可能引发后续空指针 —— 所以关键字段建议加存在性校验
map[string]interface{} 和结构体两种解析方式怎么选？
看配置是否固定、是否需要编译期校验、是否要复用字段逻辑。
- 结构体适合配置格式稳定、字段明确的场景，有类型安全、IDE 提示、字段校验方便等优势
-
map[string]interface{}灵活，适合配置键动态变化（如插件参数），但每次取值都要类型断言，容易写错，也不利于维护 - 混合用法可行：顶层用结构体，某个动态字段声明为
map[string]interface{}，比如Extras map[string]interface{} `yaml:"extras"` - 性能上差异极小，解析耗时主要在 YAML 文本分析，不在目标类型；但结构体方式 GC 压力略低（无反射创建大量 interface{}）
Go 1.16+ 中 os.ReadFile 和 embed.FS 的 yaml 加载差异
本地开发用 os.ReadFile 没问题，但打包进二进制时，得用 embed.FS，否则运行时报 “no such file”。
立即学习“go语言免费学习笔记（深入）”；
- 用
//go:embed config.yaml声明变量后，必须通过fs.ReadFile读，不能用os.ReadFile -
embed.FS不支持通配符或目录遍历，每个文件需显式声明；路径是相对于 go:embed 注释所在文件的相对路径 - 如果配置文件在子目录（如
etc/config.yaml），embed 声明要写//go:embed etc/config.yaml，读取时路径也得写全：embedFS.ReadFile("etc/config.yaml") - 测试时容易忽略 embed 行为 —— 单元测试仍走
os.ReadFile，而 main 函数走 embed，导致行为不一致；建议封装统一读取函数，测试时可注入 fs 接口
YAML 解析本身不难，真正卡住人的往往是结构体导出规则、embed 路径绑定时机、以及 map 类型字段的隐式初始化边界 —— 这些地方一错，错误信息又不直观，容易反复试错。
