有次同事发来一个 YAML 文件，里面有 2000 多行，没有缩进，各种对齐错误，用 Ansible 执行时报错“expected
, but found ' '”。我帮他格式化后才发现，原来是把列表写成了字典，少了一个短横线。后来我干脆写了个 YAML/XML 格式化校验工具，放到 VidDown 上。这篇文章讲讲工具怎么用、常见错误有哪些、以及我是怎么解析和格式化的。
一、这个工具能做什么？
YAML / XML 格式化与校验工具用于：
- 自动格式化：把杂乱的 YAML 或 XML 整理成缩进规范的文本，YAML 推荐 2 空格，XML 推荐 2 或 4 空格。
- 语法校验：检测是否有括号不匹配、缩进错误、标签未闭合等问题。
- 错误定位：解析失败时，提示行号和附近内容，方便修改。
- 下载结果：格式化后的内容可下载为
.yaml或.xml文件。
支持 YAML 1.2 标准和 XML 1.0/1.1。
🌐 在线使用：https://www.viddown.cn/tools/yaml-xml-tool/
💡 术语解释：
- YAML：一种人类可读的数据序列化格式，常用于配置文件（如 Docker Compose、Kubernetes、Ansible）。
- XML：可扩展标记语言，用于数据交换（如 WebService 配置文件、Android 布局文件）。
- 格式化：将代码按统一的缩进、换行规则重新排版，不改变语义。
- 校验：检查语法是否符合规范，例如标签是否闭合、引号是否匹配。
二、如何使用？（三步搞定）
2.1 输入源数据
在文本框内粘贴 YAML 或 XML 内容，也可以直接点击 “YAML 示例” 或 “XML 示例” 按钮快速加载。
2.2 选择格式化
- 点击 “YAML 格式化” 按钮 → 工具会校验 YAML 语法，若无误则显示美观的格式化文本。
- 点击 “XML 格式化” 按钮 → 工具会校验 XML 的标签闭合、属性引号等，然后格式化。
2.3 查看输出或错误
- 成功时，下方显示格式化后的结果，可点击“复制”或“下载为文件”。
- 失败时，下方显示错误详情，包括行号、错误类型和附近几行内容。
三、常见错误及修复建议
3.1 YAML 常见错误
① 缺少空格（最常见）
# 错误
key:value
# 正确
key: value
工具会提示：(
② 缩进不一致
# 错误
key1:
subkey: value
subkey2: value2 # 三个空格，与上一行两个空格不对齐
错误提示：expected
③ 列表少写了短横线
# 错误
items:
- a
b
工具会报错：mapping values are not allowed here。修复：每项以 - 开头。
④ 特殊字符未转义
description: 这句话包含了冒号: 会报错
修复：用引号包裹 description: "这句话包含了冒号: 会报错"。
3.2 XML 常见错误
① 标签未闭合
<root>
<name>张三
</root>
错误提示：Opening and ending tag mismatch。修复：添加 。
② 属性值缺少引号
<root attr=value/>
错误提示：Attribute value must be quoted。修复：attr="value"。
③ 注释格式错误
<!-- 注释内容 -- >
错误提示：XML comment not terminated。修复：注释必须以 --> 结尾。
四、实战场景
场景1：从网上复制了一段 YAML 配置，粘贴后无法使用
操作：粘贴到工具 → 点击“YAML 格式化” → 看到错误行号 → 手动修正 → 再次格式化 → 成功，下载或复制使用。
场景2：XML 文件很大，想统一缩进
操作：上传或粘贴 → 点击“XML 格式化” → 工具自动添加换行和缩进 → 下载整齐的版本。
场景3：团队要求 YAML 文件使用 2 空格缩进，但你的编辑器设置不同
操作：把 YAML 丢进工具，一键格式化为标准风格，不再担心缩进不一致引发的 Git 冲突。
五、技术实现（给开发者看）
5.1 YAML 处理（Python 示例）
核心使用 yaml 库：
import yaml
import sys
def format_yaml(content):
try:
data = yaml.safe_load(content)
return yaml.dump(data, default_flow_style=False, allow_unicode=True, indent=2)
except yaml.YAMLError as e:
error_line = getattr(e, 'problem_mark', None).line + 1 if e.problem_mark else 0
return {"error": str(e), "line": error_line}
5.2 XML 处理
使用 lxml.etree：
from lxml import etree
def format_xml(content):
try:
parser = etree.XMLParser(remove_blank_text=True, recover=False)
root = etree.fromstring(content, parser=parser)
return etree.tostring(root, pretty_print=True, encoding='unicode')
except etree.XMLSyntaxError as e:
return {"error": str(e), "line": e.lineno}
5.3 错误定位
1、YAML 的 YAMLError 对象中可以通过 problem_mark.line 获取行号（从 0 开始，显示时 +1）。
2、XML 的 XMLSyntaxError 自带 lineno 属性。
工具会将错误信息和附近几行（前后各 2 行）提取出来，方便快速定位。
六、问题汇总（开发与使用中踩过的坑）
1. 大文件格式化卡死
原因：某些 YAML 库（如 PyYAML）对大文件（10MB+）处理较慢。
解决：工具在前端会限制文件大小（例如 5MB），超过时提示“文件过大，请减小文件大小或分段处理”。
2. XML 有命名空间时格式化后丢失前缀
原因：lxml 默认会合并命名空间。
解决：使用 etree.register_namespace() 保留原有前缀，工具后端已做处理。
3. 用户输入的 YAML 包含 !!python/object 等自定义标签
原因：PyYAML 默认支持 Python 对象序列化，可能带来安全风险（反序列化漏洞）。
解决：工具使用 yaml.safe_load 而非 yaml.load，只允许标准 YAML 标签，遇到自定义标签会报错并提示“不支持 Python 对象”。
4. 格式化后注释丢失
原因：YAML 库在加载数据时会丢弃注释。
解决：这是一个已知限制。如果需要保留注释，建议使用专门的 YAML 编辑工具或手动添加。工具会给出提醒。
5. 用户复制 XML 时包含 BOM（不可见字符）
现象：ValueError: Unicode string with BOM。
解决：前端自动去除 UTF-8 BOM（\uFEFF），避免解析错误。
七、与命令行工具对比
工具 优点 缺点
本工具（网页版） 可视化，错误定位清晰，无需安装 依赖网络，不能处理超大文件
yamllint + yq 功能强大，可集成 CI 需要安装，输出不直观
xmllint --format Linux 自带 错误信息不够友好
八、一点小建议
1、写 YAML 时：永远用空格，不要用 Tab；数组项前面加 -；字符串中包含特殊字符时用单引号或双引号。
2、写 XML 时：推荐使用 IDE 的自动格式化插件（如 VS Code 的 “XML Tools”），也可以在线工具预处理。
3、提交代码前，先用本工具校验一遍 YAML/XML，避免 CI 失败。
4、如果文件内容涉及敏感信息（如密码），建议使用离线版本的工具（本工具纯前端处理，不上传服务器，可放心使用）。
九、总结
YAML 和 XML 在日常开发中无处不在，但它们的语法细节很容易出错。VidDown 的这个工具提供实时格式化、语法校验、错误定位三位一体的帮助，让你不再为缩进和标签而烦恼。
如果你还没试过，现在就去 https://www.viddown.cn/tools/yaml-xml-tool/ 体验一下，把你的杂乱的配置文件“一键理顺”。
附录：错误速查表
错误现象 可能原因 修复方法
mapping values are not allowed here 缺少冒号后的空格 补一个空格
expected <block end>, but found '<scalar>' 缩进不一致 统一空格数
unexpected end of stream 文件不完整或括号未闭合 检查是否有未配对的大括号/中括号
Opening and ending tag mismatch XML 标签未配对 补全闭合标签
Attribute value must be quoted 属性值没加引号 加上双引号或单引号
XML comment not terminated 注释格式错误 确保以 --> 结尾