推荐用 github.com/spf13/viper 读取配置，因其支持多格式、多源合并、优先级规则（flag > env > file > default）及热重载等，避免手写解析逻辑带来的路径、大小写、空值等常见坑。

Go 初级项目读取配置文件，推荐直接用 github.com/spf13/viper —— 它能覆盖 95% 的常见需求，且不用自己写解析逻辑、环境切换、热重载等胶水代码。

为什么别手写 json.Unmarshal 或 yaml.Unmarshal

新手常从 os.ReadFile + json.Unmarshal 入手，但很快会遇到这几个实际卡点：

• 配置要支持多种格式（config.json / config.yaml / .env），每换一种就得改解析逻辑
• 本地开发用 dev.yaml，测试环境要自动加载 test.yaml，得手动拼路径+判断 os.Getenv("ENV")
• 想加一个命令行参数覆盖某个配置项（比如 --port 8081），又得额外处理 flag 和优先级
• 后续要加远程配置中心（如 etcd、Consul），现有结构基本推倒重来

viper 内置了格式自动识别、多源合并、优先级规则（flag > env > config file > default），省掉这些“轮子债”。

viper 最简可用配置模板

以下是最小可运行示例，支持 config.yaml + 环境变量 + 默认值三合一：

package main

import (
	"fmt"
	"log"
	"github.com/spf13/viper"
)

func initConfig() {
	viper.SetConfigName("config")      // 不带后缀
	viper.SetConfigType("yaml")        // 显式指定，避免自动探测失败
	viper.AddConfigPath(".")           // 查找路径：当前目录
	viper.AddConfigPath("./conf")      // 或 conf/ 目录（更推荐）
	viper.AutomaticEnv()               // 自动读取环境变量（如 APP_PORT → viper.Get("port")）
	viper.SetEnvPrefix("APP")          // 环境变量前缀
	viper.SetDefault("port", 8080)     // 默认值
	viper.SetDefault("debug", false)

	if err := viper.ReadInConfig(); err != nil {
		log.Fatalf("读取配置失败: %v", err)
	}
}

func main() {
	initCo
nfig()
	fmt.Printf("port=%d, debug=%t\n", viper.GetInt("port"), viper.GetBool("debug"))
}

对应 config.yaml 文件内容：

port: 3000
debug: true

运行时设置 APP_DEBUG=false，输出就是 port=3000, debug=false —— 环境变量优先级高于 YAML。

容易踩的坑：路径、大小写、空值判断

初级项目最常因这三点报错或行为异常：

• viper.AddConfigPath 必须在 viper.ReadInConfig() 前调用，否则找不到文件
• YAML 键名默认转为小写（DB_URL → db_url），若用 viper.Get("DB_URL") 会返回 nil；统一用小写 key（viper.Get("db_url")）或启用 viper.SetEnvKeyReplacer(strings.NewReplacer("_", ".")) 改写规则
• viper.GetString("missing") 返回空字符串而非 panic，但你可能需要区分“没配”和“配了空字符串”，此时用 viper.IsSet("missing") 判断是否存在
• 如果配置文件里写了 timeout: null（YAML），viper.GetInt("timeout") 返回 0，不是错误 —— 这是 Go 类型转换的隐式行为，需结合 IsSet 校验

后续扩展不撕裂现有结构

当项目长大，这些演进可以平滑叠加：

• 加远程配置：只多一行 viper.AddRemoteProvider("etcd", "http://127.0.0.1:2379", "config.yml")，再调 viper.ReadRemoteConfig()
• 热重载：监听文件变化后执行 viper.WatchConfig() + viper.OnConfigChange 回调
• 结构体绑定：定义 type Config struct { Port int `mapstructure:"port"` }，然后 viper.Unmarshal(&cfg) —— 比逐个 GetXXX 更易维护

真正难的从来不是“怎么读配置”，而是“配置变更时，哪些服务要重启、哪些能热更新、哪些必须校验合法性”。viper 把读的环节稳住了，剩下的才是业务该花精力的地方。