Go 语言解析 YAML 配置文件的两种方式详解

花开有时

发布时间：2026-10-15 | 4人浏览过

原创

在 Go 开发中，使用 YAML 存储配置十分普遍。本文详细介绍利用 gopkg.in/yaml.v3 和 github.com/spf13/viper 两个库解析 YAML 的配置的方法，涵盖从基础依赖安装到完整代码示例。

结果与目标

我们的目标是通过编程手段获取外部 YAML 格式的文件内容，并将其转换为 Go 中的数据结构（如结构体或 Map）或键值对集合，以便程序直接使用。

准备条件

在开始编码前，需确保 Go 环境已就绪，并准备好需要解析的配置文件。以下是一个标准的 YAML 测试文件内容：

mysql:
  url: 127.0.0.1
  port: 3306

redis:
  host: 127.0.0.1
  port: 6379

真实操作顺序

第 1 步：安装第三方依赖

根据选择的技术方案，安装相应的包。yaml.v3 是官方维护的低层解析库，Viper 则提供了更高层级的配置管理功能。

方案 A (yaml.v3)：执行命令 go get gopkg.in/yaml.v3。
方案 B (Viper)：执行命令 go get github.com/spf13/viper。

第 2 步：使用 yaml.v3 将内容解析为结构化数据

此方案的核心是利用 Unmarshal 函数将字节流反序列化为 Go 结构体或 Map。这种方式灵活度高，但需要手动处理文件 IO 操作。

首先定义与 YAML 层级对应的结构体：

import (
	"fmt"
	"gopkg.in/yaml.v3"
	"os"
)

type Config struct {
	Mysql Mysql `json:"mysql"`
	Redis Redis `json:"redis"`
}

type Mysql struct {
	Url  string
	Port int
}

type Redis struct {
	Host string
	Port int
}

接着读取文件并完成解析：

func main() {
	// 1. 读取文件原始数据
	dataBytes, err := os.ReadFile("test.yaml")
	if err != nil {
		fmt.Println("读取文件失败：", err)
		return
	}
	fmt.Println("yaml 文件的内容: \n", string(dataBytes))

	// 2. 解析为结构体
	config := Config{}
	err = yaml.Unmarshal(dataBytes, &config)
	if err != nil {
		fmt.Println("解析 yaml 文件失败：", err)
		return
	}
	fmt.Printf("Config → %+v\n", config)

	// 3. 解析为 Map（可选）
	mp := make(map[string]any)
	err = yaml.Unmarshal(dataBytes, mp)
	if err != nil {
		fmt.Println("解析 Map 失败：", err)
		return
	}
	fmt.Printf("Map → %+v\n", mp)
}

运行后，控制台会输出原始的 YAML 字符串以及解析成功后的结构体和 Map 内容。

第 3 步：使用 Viper 管理配置

Viper 简化了配置查找逻辑，自动支持 JSON、TOML、YAML 等多种格式，甚至能监听配置变更。适用于需要对配置做统一管理的项目。

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

func main() {
    // 设置配置文件的文件名（不含扩展名）
    viper.SetConfigName("test")
    // 设置文件格式
    viper.SetConfigType("yaml")
    // 添加搜索路径
    viper.AddConfigPath("./config")
    
    // 读取配置，若找不到文件或格式错误将报错
    err := viper.ReadInConfig()
    if err != nil {
            panic(fmt.Errorf("fatal error config file: %w", err))
    }
    
    // 直接通过 Key 获取值
    fmt.Println(viper.Get("mysql"))      // map[port:3006 url:127.0.0.1]
    fmt.Println(viper.Get("mysql.url")) // 127.0.0.1
}

通过调用 Get 配合点号（`.`）语法，可以直接访问嵌套字段，无需额外定义结构体。