本文介绍在 Python 中使用 Jinja2 渲染 YAML 模板时，多行字符串（如 | 块标量）被错误转义为带换行符的单引号字符串的问题，并推荐使用 ruamel.yaml 替代 PyYAML 实现保真解析与输出。
本文介绍在 python 中使用 jinja2 渲染 yaml 模板时，多行字符串（如 `|` 块标量）被错误转义为带换行符的单引号字符串的问题，并推荐使用 `ruamel.yaml` 替代 `pyyaml` 实现保真解析与输出。
在使用 Jinja2 渲染 YAML 配置模板时，一个常见痛点是：当模板中包含 YAML 原生多行字符串（例如 proxy.istio.io/config: | 后接缩进内容），经 jinja2.Template.render() 渲染后，再用 yaml.safe_load() 解析，原始的块字面量（literal block scalar）会丢失其 | 风格，退化为带 \n 和首尾单引号的普通字符串——这不仅破坏可读性，更可能导致下游工具（如 kubectl apply 或 Istio 控制面）无法正确识别嵌套 YAML 结构。
根本原因在于：PyYAML 并非为 round-trip 场景设计。它默认将加载后的 YAML 节点统一转换为 Python 原生类型（如 str），丢弃了原始的样式信息（如 |、>、引号类型、锚点/别名等）。即使你尝试 |> 或 >- 等变体，也无法在 safe_load() → safe_dump() 流程中恢复原始格式。
✅ 推荐解决方案：迁移到 ruamel.yaml
ruamel.yaml 是专为 YAML 1.2（当前标准）设计的现代解析器，原生支持保留注释、锚点、缩进及块标量风格。它能准确识别 | 块并维持其结构完整性：
from ruamel.yaml import YAML
from pathlib import Path
yaml = YAML()
# 可选：保留双引号、避免自动折叠长行
# yaml.preserve_quotes = True
# yaml.width = 4096
# 加载原始模板（含 | 块）
template_path = Path("template.yaml")
data = yaml.load(template_path)
# 渲染后仍保持 | 样式（需配合 jinja2 + ruamel.yaml.jinja2 插件）
# 若仅需解析已渲染的 YAML 字符串：
rendered_yaml_str = render_template(template_path, context) # 你的 Jinja2 函数
parsed_data = yaml.load(rendered_yaml_str) # ✅ 自动识别 | 块，不转义为 '...\n...'⚠️ 关键注意事项：
- 不要混用 PyYAML 和 ruamel.yaml：二者 API 不兼容，尤其 safe_load() vs yaml.load()；统一替换所有 import yaml 为 from ruamel.yaml import YAML。
-
Jinja2 模板需先“预处理”再加载？ 若模板本身含 {{ }} 占位符（即未渲染的 .j2 文件），直接 yaml.load() 会报错（语法非法）。此时应使用 ruamel.yaml.jinja2 插件：
pip install ruamel.yaml.jinja2
它提供 Jinja2Preprocessor，可将 Jinja2 模板临时转为合法 YAML（占位符转为带注释的伪值），修改后再还原——适合需要动态更新 YAML 内部字段的场景。
-
输出控制：若需确保 | 风格始终生效，可在赋值时显式设置样式：
from ruamel.yaml.scalarstring import LiteralScalarString data['deployment']['annotations']['proxy.istio.io/config'] = LiteralScalarString( "concurrency: 1\nconcurr222ency: 1\nconcurrenc33y: 1\nf: 3" )
? 总结：对于 Kubernetes、Istio 等强依赖 YAML 格式语义的场景，ruamel.yaml 是 PyYAML 的必要升级。它不止解决多行字符串失真问题，更为 YAML 配置的可维护性、可审计性与自动化注入提供坚实基础。请优先在新项目中采用，并逐步迁移存量逻辑。
