Python怎样操作YAML配置文件？PyYAML使用指南

星夢妙者

发布时间：2025-08-19 17:16:01

586人浏览过

来源于php中文网

原创

使用pyyaml操作yaml文件最常用且推荐，1. 安装使用pip install pyyaml；2. 读取用yaml.safe_load()从字符串或文件加载数据，确保安全解析；3. 写入用yaml.safe_dump()将python对象转为yaml字符串或写入文件，建议设置default_flow_style=false和allow_unicode=true；4. 处理复杂结构时支持嵌套字典列表及多文档解析safe_load_all()；5. 注意安全、编码、错误处理和缩进问题，避免漏洞与解析失败，该方案完整覆盖yaml配置文件的基础操作与最佳实践。

Python怎样操作YAML配置文件？PyYAML使用指南

Python操作YAML配置文件，最常用也最推荐的库就是

PyYAML

。它能非常方便地将YAML格式的数据加载（解析）成Python中的字典、列表等原生数据结构，也能将Python对象倾倒（序列化）成YAML格式的字符串或文件。

解决方案

要使用PyYAML，首先得把它装好。很简单，用pip就行：

pip install PyYAML

装好之后，核心操作无非就是“读”和“写”。

立即学习“Python免费学习笔记（深入）”；

读取YAML数据：

通常我们从文件或者字符串中读取YAML。这里强烈推荐使用

yaml.safe_load()

。

从字符串加载：

import yaml

yaml_string = """
name: Alice
age: 30
isStudent: false
courses:
  - title: Math
    credits: 3
  - title: Physics
    credits: 4
address:
  street: 123 Main St
  city: Anytown
"""

data = yaml.safe_load(yaml_string)
print("从字符串加载的数据：")
print(data)
print(f"姓名: {data['name']}, 年龄: {data['age']}")

从文件加载：

假设你有一个名为

config.yaml

的文件，内容如下：

database:
  host: localhost
  port: 5432
  user: admin
  password: mysecretpassword
server:
  port: 8080
  debug: true

那么Python代码会是这样：

import yaml

try:
    with open('config.yaml', 'r', encoding='utf-8') as file:
        config_data = yaml.safe_load(file)
    print("\n从文件加载的配置：")
    print(config_data)
    print(f"数据库主机: {config_data['database']['host']}")
except FileNotFoundError:
    print("错误：config.yaml 文件未找到。请确保文件存在。")
except yaml.YAMLError as e:
    print(f"解析YAML时出错: {e}")

写入YAML数据：

将Python对象（比如字典、列表）保存成YAML格式的字符串或写入文件。这里用

yaml.safe_dump()

。

写入到字符串：

import yaml

python_data = {
    'project': 'MyAwesomeProject',
    'version': '1.0.0',
    'settings': {
        'log_level': 'INFO',
        'cache_enabled': True
    },
    'features': ['user_auth', 'data_export', 'reporting']
}

yaml_output = yaml.safe_dump(python_data, default_flow_style=False, allow_unicode=True)
print("\nPython对象转换为YAML字符串：")
print(yaml_output)

default_flow_style=False

会让输出更接近我们平时手写的块状风格（更易读），而不是紧凑的流式风格。

allow_unicode=True

确保非ASCII字符也能正确编码。

写入到文件：

import yaml

new_config = {
    'api': {
        'key': 'your_api_key_here',
        'endpoint': 'https://api.example.com/v1'
    },
    'timeout_seconds': 30
}

try:
    with open('new_config.yaml', 'w', encoding='utf-8') as file:
        yaml.safe_dump(new_config, file, default_flow_style=False, allow_unicode=True)
    print("\n新配置已成功写入 new_config.yaml")
except IOError as e:
    print(f"写入文件时出错: {e}")

PyYAML的安装与基础使用：从零开始配置解析？

嗯，我个人觉得，PyYAML的安装真没什么可说的，一行命令搞定。但它背后的哲学和用法，就值得聊聊了。很多人可能直接就用

load()

和

dump()

，但实际上，

safe_load()

和

safe_dump()

才是更稳妥的选择。这不仅仅是“安全”那么简单，它避免了在解析未知YAML文件时可能出现的任意代码执行漏洞。你想想，如果你的应用需要处理用户上传的YAML文件，而你用了不安全的

load

，那后果不堪设想。

所以，核心思想就是：

安装：
```
pip install PyYAML
```
。如果你的环境比较复杂，比如有多个Python版本，记得用
```
python3 -m pip install PyYAML
```
来确保装到对的解释器上。

加载（读取）：永远优先使用

yaml.safe_load()

。它只会加载YAML的基本数据类型（字典、列表、字符串、数字、布尔值、null），而不会去实例化Python对象，这就堵住了安全漏洞。如果你确实需要加载自定义Python对象（通常在内部系统或完全信任的YAML源中），那才考虑

yaml.full_load()

，但那得是你明确知道自己在做什么。

import yaml

# 假设这是从外部获取的YAML数据
untrusted_yaml = """
!!python/object/apply:os.system ["echo 'Hello, world!' > /tmp/evil.txt"]
"""
# 错误示范：千万不要直接用 load() 处理不信任的来源
# data = yaml.load(untrusted_yaml, Loader=yaml.Loader) # 这行代码在老版本PyYAML中可能直接执行系统命令

# 正确且安全的做法
try:
    safe_data = yaml.safe_load(untrusted_yaml)
    print("安全加载结果:", safe_data) # 会报错或解析失败，因为它不是标准数据类型
except yaml.YAMLError as e:
    print(f"安全加载成功阻止了潜在风险: {e}")

你看，这就是

safe_load

的意义。它宁可解析失败，也要保证你的系统安全。

倾倒（写入）：使用

yaml.safe_dump()

。它会将Python对象转换为标准的YAML格式，同样不会引入任何Python特定的序列化信息，保证了输出的通用性和可移植性。

import yaml

my_settings = {
    'database': {
        'type': 'PostgreSQL',
        'host': 'db.example.com',
        'port': 5432
    },
    'logging': {
        'level': 'DEBUG',
        'file': '/var/log/app.log'
    }
}

# 写入文件，保持可读性
with open('my_settings.yaml', 'w', encoding='utf-8') as f:
    yaml.safe_dump(my_settings, f, default_flow_style=False, allow_unicode=True)
print("my_settings.yaml 已生成。")

对我来说，每次写配置文件，我都会习惯性地加上

default_flow_style=False

，这样生成的YAML文件看起来更舒服，符合人类阅读习惯。否则，它可能会把一些简单的字典或列表写成一行，比如

{key: value, other: value}

，这在调试的时候可不那么友好。

Codiga

可自定义的静态代码分析检测工具

下载

处理复杂的YAML结构：嵌套、列表与多文档解析？

YAML的强大之处，就在于它能非常自然地映射复杂的数据结构。Python的字典和列表，几乎可以无缝地和YAML的映射（Map）与序列（Sequence）对应起来。

嵌套结构：

当你的YAML文件里有层层嵌套的配置时，PyYAML会很聪明地把它们解析成嵌套的Python字典。

application:
  name: "MyApp"
  version: "1.0.0"
  environments:
    - name: "development"
      database: "dev_db"
      debug: true
    - name: "production"
      database: "prod_db"
      debug: false

对应到Python里，

application

是一个字典，它里面又包含

environments

这个列表，列表的每个元素又是一个字典。

import yaml

complex_yaml = """
application:
  name: "MyApp"
  version: "1.0.0"
  environments:
    - name: "development"
      database: "dev_db"
      debug: true
    - name: "production"
      database: "prod_db"
      debug: false
"""

data = yaml.safe_load(complex_yaml)
print("\n解析复杂嵌套结构：")
print(data)
print(f"应用名称: {data['application']['name']}")
for env in data['application']['environments']:
    print(f"  环境: {env['name']}, 数据库: {env['database']}, 调试模式: {env['debug']}")

这感觉就像在操作Python原生数据结构一样，非常直观。

多文档解析：

有时候，一个YAML文件里可能包含多个独立的YAML文档，它们之间用

---

分隔。这在Kubernetes的配置文件里非常常见，一个文件定义多个资源。PyYAML提供了

yaml.safe_load_all()

来处理这种情况。

# document1.yaml
---
kind: Deployment
apiVersion: apps/v1
metadata:
  name: my-app-deployment
spec:
  replicas: 3
---
kind: Service
apiVersion: v1
metadata:
  name: my-app-service
spec:
  selector:
    app: my-app
  ports:
    - protocol: TCP
      port: 80
      targetPort: 8080

解析这个文件：

import yaml

multi_doc_yaml = """
---
kind: Deployment
apiVersion: apps/v1
metadata:
  name: my-app-deployment
spec:
  replicas: 3
---
kind: Service
apiVersion: v1
metadata:
  name: my-app-service
spec:
  selector:
    app: my-app
  ports:
    - protocol: TCP
      port: 80
      targetPort: 8080
"""

print("\n解析多文档YAML：")
documents = yaml.safe_load_all(multi_doc_yaml)
for doc in documents:
    print(f"--- 新文档 (类型: {doc['kind']}) ---")
    print(doc)

safe_load_all()

返回的是一个生成器，你可以像迭代列表一样遍历它，每次迭代都会给你一个独立的YAML文档。这个功能在处理一系列相关但又独立的配置时非常有用，比如微服务架构中，一个文件定义多个服务的配置。

避开PyYAML的坑：安全、编码与错误处理实践？

用PyYAML，或者说用任何处理外部数据的库，都得有点“警惕心”。我个人在实际项目里，除了上面提到的

safe_load

，还有几个地方是必须注意的。

1. 安全性：

safe_load

是底线，但不是万能药。

虽然反复强调

safe_load

，但它只是阻止了Python对象反序列化带来的代码执行风险。如果你的YAML文件本身包含了恶意数据（比如超长的字符串导致内存溢出，或者字典炸弹），

safe_load

是无能为力的。这种情况下，你还需要在加载后对数据进行校验（比如检查字段类型、长度、值范围）。这有点像，你用了防弹衣，但还得小心别被车撞。

2. 编码问题：UTF-8是王道，但不是唯一。

YAML文件默认通常是UTF-8编码，Python的

open()

函数也默认使用系统编码（通常也是UTF-8）。但如果你的YAML文件是用其他编码（比如GBK）保存的，而你没有指定正确的

encoding

参数，那就会遇到

UnicodeDecodeError

。

# 假设有一个非UTF-8编码的YAML文件
# with open('non_utf8_config.yaml', 'r', encoding='gbk') as file:
#     data = yaml.safe_load(file)
# 记得用正确的编码打开文件

所以，养成好习惯，明确指定

encoding='utf-8'

，这能省去很多不必要的麻烦。

3. 错误处理：解析失败是常态。

YAML语法非常依赖缩进和冒号等符号，一个空格不对，或者少了冒号，PyYAML就会抛出

yaml.YAMLError

。在实际应用中，尤其是在读取用户可编辑的配置文件时，你必须预料到这些错误并妥善处理。

import yaml

malformed_yaml = """
key: value
  nested: oops # 缩进错误
another_key:
- item1
- item2
"""

try:
    data = yaml.safe_load(malformed_yaml)
    print("成功加载了畸形YAML（这不应该发生）:", data)
except yaml.YAMLError as e:
    print(f"\n捕获到YAML解析错误：{e}")
    print("通常，这里应该记录日志，并给用户友好的提示。")
except Exception as e: # 捕获其他可能的异常
    print(f"捕获到未知错误：{e}")

通过

try...except yaml.YAMLError

，你可以优雅地捕获解析错误，并给出有用的提示，而不是让程序直接崩溃。这对于提升用户体验和系统稳定性非常重要。

4. 缩进：YAML的“命门”。

我见过太多因为缩进问题导致的YAML解析失败。YAML不像JSON那样用花括号和方括号明确界定结构，它完全依赖空格缩进。通常是2个或4个空格，不能是Tab。虽然PyYAML在解析时会尝试容忍一些小问题，但严格遵守规范能避免99%的缩进错误。

# 正确的缩进
parent:
  child1: value1
  child2: value2
    grandchild: value3

# 错误的缩进示例 (混合了Tab和空格，或者不一致的空格数量)
# parent:
#   child1: value1
#     child2: value2 # 这里如果用了Tab，就可能出问题

我的建议是，使用一个支持YAML语法高亮和自动缩进的编辑器（比如VS Code、PyCharm），它能帮你规避很多这类问题。

总的来说，PyYAML是一个非常成熟和强大的库，但用起来也需要一点点“匠心”。理解它的安全机制，注意编码细节，并做好错误处理，你的配置文件操作就会顺畅很多。当然，如果你对保持YAML文件的注释、原始顺序等有特别高的要求，可以考虑