viper.ReadInConfig()只加载首个匹配文件，因其设计为“按名查找首个”，非自动合并；需用MergeConfig()手动叠加多文件，顺序即优先级，且环境变量穿透嵌套字段须配合SetEnvKeyReplacer。
为什么 viper.ReadInConfig() 总是只加载一个文件
viper.ReadInConfig() 的设计就是“按名找第一个”，不是“扫描合并同前缀文件”。比如你放了 config.yaml 和 config.prod.yaml 在同一目录，调用 viper.SetConfigName("config") 后，它只会加载字典序靠前的那个（Linux 下通常是 config.yaml），压根不会继续找 config.prod.yaml。
常见错误现象：viper.Get("database.host") 返回空，但 config.prod.yaml 里明明写了；或者本地调试开关没生效——因为那个文件根本没被读到。
- 必须用
viper.MergeConfig()手动叠加，顺序即优先级：先基础、再环境、最后覆盖 -
MergeConfig()接收[]byte，得自己调os.ReadFile()读内容，不能传路径 - 每次
os.ReadFile()都要检查err，文件不存在是合法场景，别panic - 嵌套结构（如
database）会递归合并，不是全量替换；所以config.local.yaml里只写database: { port: 5433 }就能只覆盖端口
怎么让环境变量正确穿透 database.host 这类嵌套字段
默认情况下，viper.AutomaticEnv() 只会把 DB_HOST 映射到顶层 key db_host，不会自动对应到 database.host。要穿透点号层级，必须配合同步设置：
- 调用
viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))，让database.host→DATABASE_HOST - 确保结构体字段有
yaml:"host"标签，且 YAML 里写的是host: localhost（大小写敏感） - 如果环境变量名不遵循大写+下划线规则（比如
PGHOST），得用viper.BindEnv("database.host", "PGHOST")显式绑定 - 环境变量优先级天然高于文件，只要映射成功，就不需要额外判断或赋值逻辑
配置路径和格式为什么总出 silent fail
CI/CD 容器里 os.Getwd() 常为 /，viper.AddConfigPath("./configs") 实际查的是 //configs，导致 YAML 静默失败；同时硬设 viper.SetConfigType("yaml") 会让 viper 忽略 .yml 扩展名，哪怕文件存在也报错。
立即学习“go语言免费学习笔记（深入）”；
- 用双路径：
viper.AddConfigPath("./configs")和viper.AddConfigPath(".")，覆盖不同工作目录场景 - 不调
viper.SetConfigType()，让 viper 根据文件扩展名自动识别（支持.yaml、.yml、.json等） -
viper.AddConfigPath()的路径必须真实存在，哪怕为空；若路径不存在，WatchConfig()不报错但不会监听 - 用
os.Stat()或os.ReadFile()显式检查每个候选路径，例如./configs/config.json→./configs/config.yaml→./configs/config.toml，读到第一个存在的就停
结构体 Unmarshal 为什么字段总是空或类型错乱
常见现象是 viper.Unmarshal(&cfg) 后，cfg.Database 为空或 cfg.ServerPort 是 0，根本原因不是配置没读到，而是字段没加 tag 或 tag 名不匹配。
- 所有嵌套字段必须显式声明
mapstructure:"host"，哪怕和字段名一致；顶层字段可省略，但只要有一层嵌套（如Database struct{}），内部字段就必须带 tag - 配置项含连字符（如
max-connections）时，tag 必须写成mapstructure:"max-connections"，不能驼峰 - 别用指针字段（如
*string）来“判断是否设置”，这会让逻辑变复杂且易出错 - 敏感字段（如密码）建议只从环境变量读，配置文件里留空或写占位符，避免误提交
