一、什么是 YAML

YAML 全称 YAML Ain’t Markup Language，直译：不是标记语言，是一种人类极易阅读的配置文件格式，后缀一般为 .yaml / .yml。

二、YAML 适用场景

• 程序配置文件（数据库地址、端口、账号密码、开关）
• 容器编排：Kubernetes 资源定义
• CI/CD流水线：GitHub Actions、GitLab CI
• 爬虫、AI训练、FastAPI后端项目参数管理
• 静态网站、文档项目参数配置

{
  "server": {
    "host": "127.0.0.1",
    "port": 8000
  }
}

server:
  host: 127.0.0.1
  port: 8000

三、Python 安装 pyyaml

四、YAML 基础语法（零基础必看）

4.1 键值对（字典，对应Python dict）

# config.yml
name: 小明
age: 22
is_student: true
score: 95.5
address: null

对应Python类型：字符串、数字、布尔、浮点数、None

4.2 列表（数组，对应Python list）

短横线 - 开头代表列表元素

# 普通列表
hobbies:
  - 篮球
  - 看书
  - 编程

# 行内简写列表
nums: [1,2,3,4]

4.3 嵌套字典（多层配置，最常用）

database:
  host: 127.0.0.1
  port: 3306
  user: root
  password: 123456
  pool:
    max_size: 20
    min_size: 5

4.4 多行文本

# | 保留换行
desc: |
  第一行文字
  第二行文字
  第三行

# > 自动合并换行
text: >
  这是一段很长的说明
  换行仅为美观
  读取后会合并成一行

4.5 注释

# 开头整行注释，不能写在行尾键值后面

# 服务配置
server:
  port: 8000 # 错误：行尾不支持注释

五、Python 读取 YAML 文件

5.1 准备配置文件 config.yml

app:
  name: PythonDemo
  debug: true
server:
  host: 0.0.0.0
  port: 8000
db:
  user: root
  pwd: 123456

5.2 读取代码（safe_load 安全方式）

import yaml

# 打开yaml文件读取
with open("config.yml", "r", encoding="utf-8") as f:
    data = yaml.safe_load(f)

# data 是标准Python字典dict
print(data["app"]["name"])
print(data["server"]["port"])
print(data["db"]["user"])

# 单独读取某一层
server_config = data["server"]
print(server_config["host"])

六、Python 写入/修改 YAML 文件

6.1 写入全新YAML文件

import yaml

# Python字典数据
cfg = {
    "app": {"name": "TestApp", "debug": False},
    "server": {"port": 9000, "host": "127.0.0.1"}
}

# 写入文件，sort_keys=False 不自动排序键
with open("new_config.yml", "w", encoding="utf-8") as f:
    yaml.dump(cfg, f, sort_keys=False, allow_unicode=True)

6.2 修改已有YAML配置

import yaml

# 1.读取原有配置
with open("config.yml", "r", encoding="utf-8") as f:
    data = yaml.safe_load(f)

# 2.修改参数
data["server"]["port"] = 8080
data["app"]["debug"] = False

# 3.写回原文件
with open("config.yml", "w", encoding="utf-8") as f:
    yaml.dump(data, f, sort_keys=False, allow_unicode=True)

七、safe_load 安全机制说明

yaml.load(f)

yaml.safe_load(f)

八、完整实战案例：后端项目配置管理

步骤1：创建 config/app.yml

# 项目全局配置
env: dev
log_level: INFO

# 数据库配置
mysql:
  host: 127.0.0.1
  port: 3306
  database: test_db
  user: root
  password: "123456"
  pool_size: 10

# 跨域允许域名
cors_origins:
  - http://localhost:3000
  - https://xxx.com

步骤2：封装读取配置工具 config_loader.py

import os
import yaml

def load_config(yaml_path="config/app.yml"):
    """通用加载YAML配置函数"""
    if not os.path.exists(yaml_path):
        raise FileNotFoundError(f"配置文件不存在：{yaml_path}")
    with open(yaml_path, "r", encoding="utf-8") as f:
        return yaml.safe_load(f)

# 全局单例配置
config = load_config()

if __name__ == "__main__":
    # 测试读取
    print("当前环境：", config["env"])
    print("数据库地址：", config["mysql"]["host"])
    print("跨域列表：", config["cors_origins"])

步骤3：其他文件直接导入使用

from config_loader import config

# 直接使用配置
db_host = config["mysql"]["host"]
db_port = config["mysql"]["port"]
print(f"连接数据库 {db_host}:{db_port}")

九、高频报错与解决办法

十、核心总结速查表