Golang环境变量与配置文件使用教程

在 Go Web 项目中，配置管理绝非小事——它关乎环境隔离、代码可维护性与系统安全性。本文深入浅出地介绍了如何通过“环境变量 + 配置文件”双轨机制，结合导出结构体定义、viper/kong 优先级加载（命令行 > 环境变量 > 配置文件 > 默认值）、敏感信息严格隔离（密码/API密钥绝不入文件）、启动时强制校验 required 字段，以及提供清晰的 config.example.yaml 模板等实战策略，帮你构建健壮、安全、易协作的配置体系，让每一次部署都更可靠、每一次迭代都更安心。

在 Go Web 项目中，配置管理的核心是**分离环境差异、避免硬编码、保障安全性**。推荐组合使用环境变量（用于敏感/动态值）和配置文件（用于结构化、可版本化的配置），而不是只依赖其中一种。

用结构体统一承载配置

定义一个顶层配置结构体，把数据库、HTTP服务、日志等模块的参数都组织进去。这样便于校验、序列化和 IDE 提示：

type Config struct {
    HTTP struct {
        Port     int    `env:"HTTP_PORT" default:"8080"`
        Host     string `env:"HTTP_HOST" default:"localhost"`
    }
    Database struct {
        URL      string `env:"DB_URL" required:"true"`
        MaxOpen  int    `env:"DB_MAX_OPEN" default:"20"`
    }
    Log struct {
        Level string `env:"LOG_LEVEL" default:"info"`
    }
}

注意字段需导出（首字母大写），tag 中的 env 指定对应环境变量名，required 和 default 用于约束和兜底。

用 viper 或 kong 加载配置优先级链

推荐使用 viper（成熟、支持多格式、自动监听重载）或轻量的 kong（专注 CLI + 环境变量，无依赖）。关键逻辑是按优先级合并：

• 命令行参数（如 --http.port 9000）
• 环境变量（覆盖配置文件中同名项）
• 配置文件（如 config.yaml，按 ENV=prod 自动加载 config.prod.yaml）
• 结构体上的默认 tag 值（最终兜底）

示例（viper）：

v := viper.New()
v.SetConfigName("config")
v.AddConfigPath(".")
v.AutomaticEnv() // 自动映射 OS 环境变量
v.ReadInConfig()
v.Unmarshal(&cfg)

敏感信息绝不写进配置文件

数据库密码、API 密钥、JWT 秘钥等必须通过环境变量注入。CI/CD 流水线或容器编排（如 Docker Compose、K8s Secret）中安全传入，确保配置文件可提交 Git：

• 开发时：用 .env 文件 + viper.ReadInConfig() 配合 viper.SetConfigType("env") 加载（需手动解析）
• 生产时：直接由容器运行时或部署平台注入环境变量，Go 进程启动时读取
• 验证：启动时检查所有 required:"true" 字段是否非空，否则 panic 并提示缺失项

为不同环境准备配置模板

在项目根目录放 config.example.yaml，列出所有可配字段及说明（含默认值和用途），供新成员快速上手。实际部署时复制为 config.yaml 并删减无关项。例如：

# config.example.yaml
http:
  port: 8080          # 服务监听端口
  host: "localhost"   # 绑定地址，生产建议设为 "0.0.0.0"
database:
  url: ""             # 必填，格式如 postgres://user:pass@host:5432/db
log:
  level: "info"       # debug, info, warn, error

不复杂但容易忽略的是：每次新增配置项，同步更新 example 文件和文档注释。

好了，本文到此结束，带大家了解了《Golang环境变量与配置文件使用教程》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多Golang知识！