Go 语言如何读取 .env 或 .yaml 配置文件？

Go 语言配置文件加载：从 .env 到 YAML 的选择与避坑

先说一句大实话：Go 标准库是不认 .env 文件的。想用环境变量来管理配置，就得借助第三方库，而 github.com/joho/godotenv 是目前最轻量、最直接的选择。它的核心动作很简单——把 .env 里的键值对一股脑注入到 os.Environ() 中，之后你调用 os.Getenv() 就能正常获取。但这里有几个容易踩坑的地方，值得仔细捋一捋。

最常见的问题在于：要么没检查 Load() 的返回错误导致配置为空却继续运行，要么在 main() 还没执行时就提前调用了 os.Getenv()——比如在某个 init() 函数里。结果自然是空字符串，还要花半天时间排查。正确的姿势是：在 main() 的开头立即调用 godotenv.Load()，并确保捕获错误。

if err := godotenv.Load(); err != nil {  
    log.Fatal("加载 .env 失败:", err)  
}

如果 .env 不在当前目录，传入完整路径就好：godotenv.Load(".config/.env")。多个文件可以依次加载，比如 godotenv.Load(".env.local", ".env")，注意后加载的文件会覆盖前面同名变量。还有个小提醒：godotenv 本身不处理变量引用，比如 PORT=${HTTP_PORT} 这样的写法它不认，需要手动调用 godotenv.Expand()，或者换用像 dotenv 这样的库。

Go 读取 YAML 配置：用 gopkg.in/yaml.v3 解析结构体最稳妥

如果配置内容复杂——嵌套结构、数组、类型需要明确，YAML 比 .env 合适得多。Go 标准库同样不提供 YAML 解析，但 gopkg.in/yaml.v3 是目前维护最活跃的选择（v2 已经归档了）。关键在于怎么把 YAML 映射到结构体上不出错。典型的坑是字段名大小写不匹配，或者干脆忘了写 struct tag，导致解析后字段全是零值；还有 YAML 文件里缩进空格不一致，直接触发 panic。

正确的做法是：结构体字段必须首字母大写（导出），并加上 yaml:"key_name" 标签。举个例子：

type Config struct {  
    Server struct {  
        Port int    `yaml:"port"`  
        Host string `yaml:"host"`  
    } `yaml:"server"`  
}

读取时建议用 os.ReadFile()（Go 1.16 之后推荐）代替 ioutil.ReadFile()，然后把内容传给 yaml.Unmarshal()。注意 YAML 里的布尔值要写成 true/false，数字不要加引号——不然很可能被当成字符串解析。如果某些配置项是可选的，字段类型用指针（比如 *string）或者加上 omitempty 标签，避免零值覆盖掉默认逻辑。

同时支持 .env 和 YAML：优先级和合并逻辑得自己控制

目前没有一个标准方案能自动“混合加载”两种格式。常见的做法是先读 YAML 构建基础配置，再用 .env 覆盖其中部分字段——尤其适用于敏感信息或本地调试参数。顺序和覆盖规则必须显式编码，不要依赖库的默认行为。

有一个容易忽略的细节：环境变量名通常全大写加下划线，比如 DB_HOST，而 YAML 中习惯用 snake_case，比如 db_host。这两者之间的映射需要你做一套转换逻辑。建议的做法是定义一个统一的配置结构体，让 YAML 和环境变量都映射到同一组字段上：

type Config struct {  
    DBHost string `env:"DB_HOST" yaml:"db_host"`  
}

如果想更灵活一点，可以用 github.com/mitchellh/mapstructure 把 map[string]interface{}（来自 YAML）和 os.Environ() 同时解码进同一个结构体，但需要注意类型转换失败时的 fallback 机制。生产环境建议禁用 .env，只靠环境变量注入；开发时两者共存，但务必在文档里写清优先级：环境变量 > YAML。另外，不要在 YAML 里写密码等敏感字段——这些值应该只通过环境变量注入。

为什么不用 viper？它太重，且隐藏行为多

viper 确实支持多格式和自动重载，但它引入的隐式行为容易让人陷入泥潭：自动搜索路径、缓存机制、键名 normalize（比如把 API_URL 变成 api-url），以及难以调试的优先级链。小项目或 CLI 工具里，这些特性反而增加不确定性。

真实场景中经常遇到这样的问题：修改了 .env 但程序没重启，误以为 viper 会自动热重载；或者 YAML 里写了 log-level: debug，结果 viper.Get("log_level") 取不到——因为 key 被 normalize 成了 loglevel。除非你明确需要远程配置中心（etcd/Consul）或文件监听重载，否则建议绕过 viper。如果已经用了，记得调用 viper.SetEnvKeyReplacer(strings.NewReplacer("-", "_")) 来统一环境变量风格。调试时用 viper.AllSettings() 打印最终配置，而不是只查单个 key。

说到底，配置文件读取本身并不难，真正的挑战在于：让不同环境下的配置来源清晰、不可变、可审计。YAML 适合描述性配置，.env 适合运行时注入，两者混用时一定要明确定义每一层的职责，别让加载逻辑散落在多个 init 函数里。