最轻量可控的配置方案是用GO_ENV环境变量驱动加载结构化YAML文件并显式校验；禁止AutomaticEnv()和init()读配置，GO_ENV须在main首行读取冻结，值限定dev/test/prod，失败直接panic，路径固定为./configs/config.<env>.yaml，禁用ldflags注入，结构体分层嵌套、字段导出、tag严格匹配，环境变量仅覆盖敏感项且需显式绑定，敏感字段YAML留空+代码校验非空，配置加载封装为可测试函数，避免全局状态。
直接用 GO_ENV 环境变量驱动配置加载，配合结构化 YAML 文件 + 显式校验，是最轻量、最可控的方案。别用 viper.AutomaticEnv() 自动映射，也别在 init() 里读配置——这两点踩坑率最高。
GO_ENV 必须在 main 入口第一行读取并冻结
环境标识一旦被其他包间接读取，就可能被覆盖或延迟，导致配置加载错乱。所有后续逻辑必须基于这个确定值分支，不能反复调用 os.Getenv("GO_ENV")。
-
GO_ENV值只允许是dev、test、prod（或明确约定的枚举），禁止 fallback 到默认值；加载失败直接panic，不启动比带错配置运行更安全 - 配置文件路径硬编码为
./configs/config.<env>.yaml，避免拼写歧义（比如config.development.yaml和config.dev.yaml混用） - 不要用
go build -ldflags "-X main.Env=..."注入环境名——编译时固化无法调试，且 Docker 运行时无法动态切换
结构体定义必须分层嵌套，禁用 map[string]interface{}
YAML 解析进 map[string]interface{} 会让字段不可跳转、类型无检查、IDE 失效，后期加字段或改类型极易漏改。
- 通用字段放顶层结构体，如
Server.Port、Database.Host - 环境专属字段（如
SentryDSN、LogLevel）不塞进主结构体，而是单独定义type ProdConfig struct { Config; SentryDSN string }，再由构造函数做非空校验 - 所有字段必须导出（首字母大写），YAML tag 名与配置文件 key 严格一致，大小写敏感
环境变量只用于覆盖，不用于主配置来源
纯靠环境变量管理全部配置（如 DB_HOST、REDIS_ADDR）会导致配置分散、难维护、易遗漏。正确做法是：YAML 提供基础骨架，环境变量仅覆盖少数敏感项。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
立即学习“go语言免费学习笔记（深入）”；
- 用
viper.BindEnv("database.dsn", "DATABASE_DSN")显式绑定，而不是viper.AutomaticEnv()—— 后者会把所有DB_*变成database.*，拼错就静默失败 - 本地开发用
godotenv.Load(".env.local")加载覆盖，CI/CD 中禁用.env*加载，强制走真实环境变量，防密钥误提交 - 敏感字段（如密码、密钥）在 YAML 中留空，靠环境变量注入；但必须在代码中校验非空：
if cfg.Database.DSN == "" { return errors.New("DATABASE_DSN required in prod") }
测试时必须绕过全局配置加载逻辑
如果配置加载写在 init() 或包级变量里，单元测试根本没法注入 mock 配置，一跑就 panic。
- 所有配置加载必须封装为可导出函数，例如
func LoadConfig(env string) (*Config, error) - 业务逻辑通过参数接收
*Config，而非依赖全局单例或包变量 - 测试时直接构造结构体实例传入，或用
os.Setenv+defer os.Unsetenv控制变量，避免污染进程环境
真正容易被忽略的是：环境变量覆盖和 YAML 字段的类型一致性。比如 YAML 里写 port: 8080（int），环境变量设 SERVER_PORT="8080"（string），viper 默认不会报错，但 GetInt 会返回 0。这种隐式转换问题，只在生产环境暴露，查起来极慢。
