viper.ReadInConfig() 报“Config File Not Found”主因是未显式设置配置路径，它仅在当前工作目录查找一次；需调用viper.AddConfigPath()指定路径，且viper.SetConfigType()必须在读取前调用并准确设为"yaml"等合法类型。
viper.ReadInConfig() 报 “Config File Not Found” 不是文件丢了，是你没告诉它去哪找
默认行为极其保守：viper 只在 os.Getwd() 返回的当前工作目录里查一次，不递归、不猜路径、不扫常见目录（比如 ./configs 或 ./etc）。哪怕你把 config.yaml 放在项目根下，go test ./cmd 时工作目录变成 ./cmd，它就真找不到。
- 必须显式调用
viper.AddConfigPath("./configs")或viper.AddConfigPath(".")，支持多次调用，按添加顺序查找 - 文件名要匹配：
viper.SetConfigName("app")+viper.SetConfigType("yaml")→ 它只找app.yaml，不是config.yaml - 构建或测试时路径易变，建议启动时加一行
fmt.Println("cwd:", os.Getwd())确认实际位置 - 别依赖 IDE 启动目录；容器或 CI 中更不可靠，路径必须显式传入或通过
runtime.Caller动态推导
viper.SetConfigType("yaml") 是硬性要求，不是可选项
后缀不是万能的。当文件叫 config（无后缀）、app.conf，或你用 embed.FS 读成字节流再调 viper.ReadConfig(bytes.NewReader(data)) 时，viper.SetConfigFile() 完全失效，SetConfigType 是唯一出路。
立即学习“go语言免费学习笔记（深入）”；
-
viper.SetConfigType("yaml")必须在viper.ReadInConfig()或viper.ReadConfig()之前调用 - 类型名必须准确：
"yaml"、"json"、"toml"，不能写成"yml"（虽然部分版本兼容，但不保证） - YAML 文件里混入 tab 缩进会直接报
While parsing config: yaml: line X: did not find expected key，用空格缩进
viper.AutomaticEnv() 不自动映射，只开闸不引水
调了 viper.AutomaticEnv() 却拿不到环境变量值？因为默认规则只把 . 和 - 替换成 _ 并大写，database.url → DATABASE_URL，但 apiUrl 或 cacheTimeout 这类驼峰字段根本对不上。
- 必须先设前缀：
viper.SetEnvPrefix("APP")，否则所有APP_*变量都不被扫描 - 自定义映射用
viper.BindEnv("database.url", "DB_URL")，绕过默认转换规则 - 顺序不能错：
viper.AutomaticEnv()要在viper.ReadInConfig()之前，否则环境变量不参与覆盖逻辑 - 环境变量优先级高于配置文件，但前提是该键已被访问过（
viper.Get("x")或viper.Unmarshal()触发加载）
viper.Unmarshal() 静默失败，结构体字段零值大概率是 tag 或导出问题
YAML 内容正确、路径正确、viper.AllSettings() 也能打印出原始数据，但结构体字段全是零值？Viper 不报错也不 panic，它只是跳过不匹配字段。
- 结构体字段必须导出（首字母大写），小写字段永远被忽略
- 必须显式加
mapstructure:"key_name"tag，例如Port int `mapstructure:"port"`；yaml:"port"不起作用（除非你手动指定解析器） - 嵌套结构体要逐层打 tag：
Server ServerConfig `mapstructure:"server"`，不能只打顶层 - 类型必须严格匹配：
timeout: "30s"对应Timeout time.Duration才行，Timeout int会静默失败
最易被忽略的是：viper 的加载和解析是两步分离动作。调 ReadInConfig() 只是把原始数据塞进内部 map，Unmarshal() 才真正做类型转换和字段填充——而后者完全依赖结构体定义是否合规。任何一环 tag 拼错、字段未导出、类型不兼容，都只会留个零值，不会给你提示。
