推荐用 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() {
initConfig()
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 把读的环节稳住了，剩下的才是业务该花精力的地方。
