本文介绍如何为 PyYAML 注册自定义 YAML 表示器，使 pathlib.Path（如 PosixPath 或 WindowsPath）对象能被安全地序列化为 YAML 字符串，避免 RepresenterError。
本文介绍如何为 pyyaml 注册自定义 yaml 表示器，使 `pathlib.path`（如 `posixpath` 或 `windowspath`）对象能被安全地序列化为 yaml 字符串，避免 `representererror`。
在使用 PyYAML 的 safe_dump 或 safe_dump_all 序列化嵌套数据结构时，若对象中包含 pathlib.Path 实例（例如 Path("/etc/config")），默认会触发 RepresenterError：cannot represent an object。这是因为 PyYAML 的 SafeDumper 仅支持基础类型（str, int, list, dict, bool, None 等），不识别 Path 类型——与 JSON 不同，YAML 没有内置的“通用编码器钩子”（如 JSONEncoder.default），而是依赖显式的 representer 注册机制。
✅ 正确解决方案是：为 pathlib.Path 类注册一个自定义多类型表示器（multi-representer），将其统一转换为标准字符串：
import yaml
from pathlib import Path
def represent_path(dumper, path):
return dumper.represent_str(str(path))
# 全局注册：所有 Path 子类（PosixPath、WindowsPath 等）均适用
yaml.add_multi_representer(Path, represent_path)注册后，即可照常使用 safe_dump 或 safe_dump_all：
data = {
"config_dir": Path("/etc/myapp"),
"log_paths": [Path("/var/log/app.log"), Path("/tmp/debug.json")],
"enabled": True,
}
with open("config.yaml", "w") as f:
yaml.safe_dump(data, f, indent=2, default_flow_style=False)生成的 YAML 将正确显示为：
config_dir: /etc/myapp enabled: true log_paths: - /var/log/app.log - /tmp/debug.json
⚠️ 注意事项：
- ✅ 使用 add_multi_representer（而非 add_representer）可确保 Path 的所有子类（如 PosixPath, WindowsPath, PurePath）均被覆盖；
- ✅ dumper.represent_str(str(path)) 是推荐做法：str(path) 安全、跨平台，且语义清晰（等价于 os.fspath(path)）；
- ❌ 避免直接返回 dumper.represent_scalar(...) —— 它绕过类型安全检查，可能引发意外行为；
- ⚠️ 注册需在调用 dump/dump_all 之前完成，且只需执行一次（通常放在模块顶层或初始化逻辑中）；
- ? 若项目需严格隔离（如多线程/多配置场景），可创建自定义 Dumper 子类并局部注册，但绝大多数场景全局注册已足够安全。
总结：PyYAML 的可扩展性依赖于显式 representer 注册。通过三行核心代码（导入 + 函数定义 + 注册），即可无缝支持 pathlib.Path 序列化，兼顾简洁性、健壮性与可维护性。
