“config file not found”主因是viper默认仅在当前工作目录查找且不递归子目录，必须显式调用viper.addconfigpath指定路径（如"./configs"），并配合viper.setconfigname("app")和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") 是硬性要求，不是可选项
从 v1.12.0 开始，viper 移除了对 YAML 的默认支持。即使你 import "gopkg.in/yaml.v3"，也不代表 viper 能自动识别 .yaml 后缀——它只查内部注册表里“扩展名 → 解析函数”的映射，而这个映射默认为空。
- 当用
viper.SetConfigName("app")+viper.AddConfigPath("./conf")时，viper.SetConfigType("yaml")必须在viper.ReadInConfig()前调用 - 如果用
viper.SetConfigFile("./conf/app.yaml")（带完整路径和后缀），这一步可省；但一旦路径不带后缀或后缀不标准（如app.conf），SetConfigType就是唯一出路 - 类型名必须准确：
"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() 也能打印出原始数据，但结构体字段全是零——这不是解析失败，而是绑定失败。
- 结构体字段必须首字母大写（导出），否则
Unmarshal无法赋值 - 嵌套字段必须加
mapstructure:"key_name"tag，哪怕名字完全一致，例如：Host string `mapstructure:"host"` - 连字符字段（如
max-connections）必须写成`mapstructure:"max-connections"`，不能驼峰 - YAML 中的
timeout: "30s"对应Timeout time.Duration字段才安全；若写成int，会静默跳过不报错
最常被忽略的一点：viper 不会帮你推导嵌套层级的键名映射关系。你写了 database.host: 127.0.0.1，但结构体里 type Config struct { Database DBConfig } 没给 DBConfig 字段加 mapstructure:"database"，那整个 Database 子结构就根本不会被填充。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
