viper.Unmarshal忽略小写字段因未导出，需首字母大写并加结构标签；.env需godotenv.Load()加载再AutomaticEnv()；优先级为命令行>环境变量>配置文件；热重载需防抖并检查ConfigFileUsed()。
为什么 viper.Unmarshal 会忽略 struct 字段
Go 项目中用 viper.Unmarshal 加载配置时，字段值为零值（如空字符串、0、nil）却没报错，实际是字段未被赋值——根本原因是 struct 字段未导出。Viper 只能访问首字母大写的导出字段，小写字段直接跳过，不会报错也不会提示。
- 确保所有配置字段名与 struct 字段名**完全一致**（区分大小写），且字段首字母大写
- 添加
yaml、json等结构标签，例如Port int `mapstructure:"port" yaml:"port"` - 调用
viper.Unmarshal后，建议用fmt.Printf("%+v", cfg)检查实际填充结果，而非仅依赖日志
如何让 viper 正确加载 .env 文件中的环境变量
Viper 默认不自动读取 .env 文件，必须显式启用并指定路径。即使你用了 viper.AutomaticEnv()，它也只读取系统环境变量，不是文件里的键值对。
- 先用
viper.SetConfigFile(".env")指定文件，再调用viper.ReadInConfig()—— 但注意：这读的是.env作为配置源（类似 YAML），不是作为环境变量注入源 - 若想把
.env中的键映射为系统环境变量供viper.Get("KEY")使用，需在程序开头手动加载：import "github.com/joho/godotenv"
godotenv.Load(".env") -
viper.AutomaticEnv()必须在viper.ReadInConfig()之后调用，否则环境变量可能覆盖配置文件值，顺序反了容易踩坑
多个配置源冲突时，viper 的优先级怎么算
Viper 的值来源有固定优先级：命令行参数 > 环境变量 > 远程 Key/Value 存储 > 配置文件 > 默认值。同一 key 在多个源中存在时，高优先级源会覆盖低优先级源，且**不会合并嵌套结构**。
- 比如配置文件里
database: {host: "localhost", port: 5432}，而环境变量设了DATABASE_HOST=prod-db，最终得到的是{host: "prod-db", port: 0}——port被清零，因为环境变量没提供它，且 Viper 不做字段级 merge - 避免跨源混用嵌套结构；如需灵活覆盖，统一用环境变量（如
DATABASE_HOST、DATABASE_PORT），或改用viper.UnmarshalKey("database", &dbCfg)单独解构 - 调试时用
viper.AllSettings()打印完整 map，比viper.Get()更能看出哪个源实际生效
热重载配置时为何 fsnotify 事件总延迟或丢失
用 viper.WatchConfig() 启用热重载后，修改配置文件有时不触发回调，或触发两次，本质是底层 fsnotify 对某些文件系统（如 macOS 的 APFS、Docker 容器内挂载卷）事件不可靠，且 Viper 默认未去重和防抖。
立即学习“go语言免费学习笔记（深入）”；
- 不要依赖单次
fsnotify.Event.Op判断变更类型；应监听fsnotify.Write和fsnotify.Create，并加 100ms 延迟后再次viper.ReadInConfig()，防止读到半截文件 - 在
viper.OnConfigChange回调里，务必检查viper.ConfigFileUsed()是否非空，避免首次加载时误触发 - 生产环境更推荐“重启代替热重载”：配置变更 → 发送信号 → 主进程 reload，比文件监听更可控
