viper.ReadInConfig()报“Config File Not Found”主因是未显式设置配置路径，它默认仅在当前工作目录查找且不递归子目录；必须调用viper.AddConfigPath指定路径、viper.SetConfigName设文件名（不含后缀）、viper.SetConfigType设格式，三者缺一不可。
初始化 Viper 时找不到配置文件
常见错误是 viper.ReadInConfig() 报错 Config File "app" Not Found in "[. ./configs]"，本质是路径没对上。Viper 不会自动递归搜索子目录，AddConfigPath() 只指定「一级搜索目录」，且顺序影响优先级。
- 用
os.Getwd()打印当前工作目录，确认程序启动时 pwd 是你预期的根目录（不是go run main.go所在的任意子目录） -
AddConfigPath("configs")和AddConfigPath("./")同时存在时，后者会先被尝试，若当前目录下有同名但格式错误的app.yaml，Viper 会解析失败而不继续找 configs/ 下的版本 - 推荐显式拼接绝对路径：
viper.AddConfigPath(filepath.Join(workDir, "configs"))，避免相对路径歧义 - YAML 文件必须以
viper.SetConfigName("app")中的名称为准，不带扩展名；viper.SetConfigType("yaml")必须在ReadInConfig()前调用，否则默认按 JSON 解析
从 Viper 读取嵌套字段容易 panic
直接调用 viper.GetString("database.dsn") 看似简洁，但一旦 database 节点缺失或类型不对，就会返回空字符串而不报错——这在数据库连接时导致静默失败，日志里只看到 invalid DSN，很难定位是配置漏写还是路径写错。
- 优先用结构体绑定：
viper.Unmarshal(&config)，它会在字段缺失时触发明确 panic，配合panic: reflect: NumField of non-struct type类错误能快速暴露结构定义和 YAML 字段不匹配 - 如果必须用链式取值，加断言检查：
if !viper.IsSet("database.dsn") { log.Fatal("missing database.dsn") } - 注意 YAML 中布尔值写法：
debug: true是合法的，但debug: "true"会被当字符串，viper.GetBool("debug")返回 false
Gin 启动前必须完成 Viper 初始化
把 viper.ReadInConfig() 放在 gin.Default() 之后、路由注册之前看似合理，但实际风险很大——比如你在中间件里读 viper.GetString("server.mode")，而此时配置还没加载，就会拿到空值或默认零值。
- 初始化逻辑必须放在
main()最开头，或封装成initConfig()并在main()第一行调用 - 不要在 handler 函数里首次调用
viper.GetString()，因为 Gin 的 handler 是并发执行的，Viper 内部无锁，虽然读操作通常安全，但WatchConfig()触发重载时可能产生竞态 - 若需热更新，用
viper.WatchConfig()+viper.OnConfigChange()，但解绑结构体后要加sync.RWMutex保护全局 config 实例，否则并发读写 struct 字段会 panic
YAML 配置中特殊字符导致 DSN 解析失败
MySQL 密码含 @、/、: 等符号时，直接拼接 DSN 字符串会破坏 URL 结构，gorm.Open() 报错 invalid DSN: missing the slash separating the database name 或连接拒绝。
- 必须对敏感字段做 URL 编码：
url.PathEscape(viper.GetString("database.password"))，而非仅对整个 DSN 调用url.QueryEscape - DSN 拼接建议用
fmt.Sprintf显式控制顺序，避免依赖viper.Sub("database").GetString("dsn")——后者无法分离用户名、密码、host 等组件做单独编码 - 开发期可打印最终 DSN 字符串做验证：
log.Printf("DSN: %s", dsn)，肉眼确认user:pass@tcp(...)格式是否合法
