Go无内置配置加载机制，必须显式选择方案并控制时机；viper最省心但需手动SetConfigType，轻量场景用yaml.v3+godotenv组合；结构体字段未导出或tag错误导致零值；.env覆盖需手动分步实现。
viper 是最省心的通用解法，但若只读一个 YAML 或 .env 文件，gopkg.in/yaml.v3 + github.com/joho/godotenv 组合更轻量、无隐式行为。
用 viper.LoadConfig() 时总报 unknown config type
根本不是文件内容问题，而是 viper 没法靠后缀猜格式——尤其当文件叫 config（无后缀）、app.conf 或你用 embed.FS 读取字节流时。
必须在 viper.ReadInConfig() 前手动声明：viper.SetConfigType("yaml") 或 viper.SetConfigType("json")。
常见踩坑点：
- 调了
viper.SetConfigFile("config.yaml")却没设SetConfigType，viper 仍按默认逻辑查后缀，而某些构建环境会 strip 后缀 - 用
embed.FS读取后传给viper.ReadConfig(bytes.NewReader(data))，此时SetConfigFile完全无效，SetConfigType是唯一出路 -
viper.AutomaticEnv()和ReadInConfig()顺序反了：必须先AutomaticEnv()再ReadInConfig()，否则环境变量不参与覆盖
go test 时 config.yaml 找不到路径
因为 go test ./pkg 的当前工作目录是 pkg/，不是项目根目录，相对路径 "config.yaml" 自然失效。
别改 os.Chdir()，也别在 init() 里自动加载——那会让测试和运行时行为不一致。
正确做法是把路径作为参数传入：
- 配置加载函数定义为
func Load(configPath string) error，内部用os.ReadFile(configPath) -
main.go调用Load("config.yaml")（项目根下） -
test.go调用Load("../config.yaml")或用filepath.Join("..", "config.yaml") - 更健壮的做法：用
runtime.Caller(0)获取调用方位置，再向上找项目根，但多数场景直接传相对路径已足够
YAML 解析后结构体字段全是零值
不是 YAML 写错了，大概率是 Go 结构体字段没导出或 tag 拼错。gopkg.in/yaml.v3 只能访问首字母大写的导出字段，且必须严格匹配 yaml:"key_name" 中的 key 名（区分大小写、空格、下划线）。
典型错误：
Pandas 配置文件报告生成器
下载
使用ydata-profiling（前身为pandas-profiling）生成全面的数据质量报告，包含相关性分析、缺失值模式和基数检测。导出交互式HTML仪表板和JSON摘要。
- 字段写成
port int（小写）→ yaml.Unmarshal 直接跳过，不报错也不赋值 - tag 写成
yaml:"Port"，但 YAML 里是port: 8080→ 匹配失败，留零值 - 嵌套结构漏了外层 tag，例如
Server ServerConfig `yaml:"server"`忘了这个`yaml:"server"`，整个子结构不会被解析 - 用了缩进制表符（tab）而非空格，
yaml.v3默认 panic，加yaml.UnmarshalStrict可捕获更明确错误
想让 .env 覆盖 YAML 配置，但顺序总乱
没有库能自动“混合加载”，viper 的优先级是命令行 > 环境变量 > 配置文件 > 默认值，但它不支持把 .env 当作独立配置源来 merge。
真实可控的做法是分两步、自己控权：
立即学习“go语言免费学习笔记（深入）”；
- 先用
yaml.Unmarshal解析config.yaml到结构体，作为基础配置 - 再用
godotenv.Load(".env")加载环境变量，然后手动覆盖结构体中对应字段（如cfg.Server.Port = os.Getenv("SERVER_PORT")） - 或者用
mapstructure.DecodeHook做类型转换，再用mapstructure.Decode把os.Environ()映射过去，但需注意键名转换规则（SERVICE_PORT→service.port） - 绝对不要依赖
godotenv.Load()后直接读os.Getenv()就认为“已覆盖”——如果 YAML 里字段是*string类型，而 .env 为空，你得决定是保留 nil 还是设默认值
viper.WatchConfig() 触发后，新配置解析失败却静默丢弃，服务就可能用着旧配置连错数据库；又比如测试时用 ../config.yaml，CI 环境里目录结构稍有不同，路径就断掉。这些地方没日志、没校验、没 fallback，问题一定晚发现。 
