错误排查 · 更新于 2026-08-12
YAML 格式错误
按“现象 → 最小检查 → 可复现修复 → 成功判断 → 回滚”处理YAML 格式错误。
兼容客户端（以其官方文档和当前版本为准）
不在本站输入、上传或保存真实订阅。
前置条件
- 确认当前客户端能打开配置页面。
- 先备份已知可用配置的脱敏副本。
- 阅读对应来源与更新说明。
从现象开始，而不是反复重试
- 01
记录完整错误文字与发生时间，不要截图或转发真实订阅。
- 02
用最小配置或安全示例隔离问题范围。
- 03
检查格式、网络、权限和客户端支持范围。
- 04
仅变更一个因素后重试，并读取新日志。
mode: rule
# 仅为安全示例
proxy-groups: []配置如何阅读
这不是可直接使用的订阅。先从模式和顶层字段读起，再用最小样例验证单一改动。未知字段应回到客户端文档核验。
成功判断
错误不再出现，且日志显示新的配置已被正确读取；不要只以“能打开页面”作为成功。
常见错误
回滚方式
恢复先前已验证的脱敏备份；撤销本次单一改动；必要时关闭 TUN 或系统代理，再重新检查。
安全提醒
不要在截图、工单、搜索框或第三方工具中输入完整订阅、密码、UUID、密钥或节点地址。本站工具只在浏览器本地运行，默认脱敏展示。
来源与更新
本页更新：2026-08-12。系统要求、软件版本和发布文件以当前来源页面为准。
查看来源等级与校验方法 →下一步
客户端已经正确配置？
客户端配置落地：完成导入、权限与回退验证后，再决定是否需要服务入口。配置复验后访问官网
套餐、价格、线路与规则不在本站转述，请直接核对官网当前页面。补充更新：按报错信息定位 YAML 格式错误
简答：先不要整份重写配置：把报错行前后各 3 行单独检查，优先排除 Tab、缩进不一致、未闭合引号和冒号后缺少空格；语法通过后，还要继续检查配置字段、类型和平台要求。
定义：YAML 格式错误，是 YAML 解析器无法按缩进、标点、引号、集合层级或文档边界规则读取配置文件的问题。
先试这一步：从报错行向前检查 3 类问题
如果客户端提示 YAML 解析失败，先复制完整报错文字和行号，不要把真实订阅、密钥或令牌上传到在线工具。报错行不一定是真正原因，上一行未闭合的引号、少写的冒号、错误缩进，往往会让解析器在下一行才报错。
- 检查报错行及前 3 行：确认每一层只使用空格，没有混入 Tab；同一层级的键和值保持一致缩进。
- 检查结构符号：映射使用
key: value，列表项使用- item；冒号、短横线后通常要有空格。 - 检查字符串边界：单引号、双引号、方括号和花括号是否成对出现；包含
#、:、{}或[]的普通文本，必要时改为引号字符串。
YAML 1.2.2 规范说明，块集合依靠缩进表达范围，序列项以短横线和空格开始，映射键值以冒号和空格分隔；映射键还必须保持唯一。可查看YAML 1.2.2 官方规范核对语法边界。
报错信息速查：原因与最小修复示例
| 常见报错或现象 | 优先检查 | 错误示例 | 修复方向 |
|---|---|---|---|
mapping values are not allowed here | 上一行缩进、冒号位置、字符串是否应加引号 | name: demo: test | name: "demo: test" |
bad indentation 或缩进错误 | 同级键是否使用相同空格数，是否混入 Tab | server: | server: |
did not find expected key | 前一项是否缺少冒号，列表项层级是否错位 | server | server: |
| 解析器提示字符串未结束 | 单引号或双引号是否成对，双引号内的反斜杠是否正确 | name: "demo | name: "demo" |
| 文件能解析但平台拒绝 | 字段名、必填项、数据类型、版本和 schema | port: "443" | 按平台要求确认应为数字还是字符串，不能只看 YAML 语法 |
上表中的修复示例只用于说明 YAML 结构，不是任何客户端的完整配置。YAML 规范将解析、节点结构和类型解析区分开；因此“能被 YAML 解析”不等于“目标平台一定接受”。
最容易导致 YAML 格式错误的 7 个细节
- Tab 不能代替缩进空格：编辑器中启用“显示空白字符”，将 Tab 转为空格后再保存。YAML 的块结构依靠缩进表达范围，Tab 混用会使层级无法稳定判断。
- 同级缩进必须一致：不要求所有文件都固定使用 2 个或 4 个空格，但同一文件应保持一致。列表是否额外缩进，还要符合所用解析器和项目约定。
- 冒号后留空格：
name: demo比name:demo更明确；当值本身包含冒号时，使用引号，例如url: "https://example.test/a:b"。 - 短横线表示列表项：
servers:下一层可写为- host-a；不要把短横线和普通文本混在同一层。 - 井号可能启动注释：
name: demo # test中井号后的内容通常是注释；若井号属于值的一部分，使用引号，例如name: "demo # test"。 - 引号要成对：双引号支持转义，单引号中的单引号需要按 YAML 规则表示；不确定时可先把复杂文本改成正确闭合的双引号字符串。
- 重复键不要忽略：YAML 规范要求映射键唯一。即使某些解析器没有立即报错，重复键也可能造成后一个值覆盖前一个值。使用 linter 检查重复键。
YAML 1.2.2 官方规范还列出了流式集合中的方括号、花括号和逗号，以及保留指示符等边界；当普通文本以这些字符开头或包含复杂标点时，优先使用引号或改成块写法。
YAML 1.1 与 1.2：语法通过但类型不对怎么办
有些问题不是“格式错误”，而是同一段文本在不同 YAML 处理器或 schema 下被解析成了不同类型。YAML 1.2 引入 core schema 作为推荐默认 schema，和 YAML 1.1 的类型解析存在差异；例如 yes、no、on、off 这类值，不应在不了解目标解析器规则时直接当作布尔值使用。相关变化可查阅 YAML 官方的版本变化说明。
- 需要字符串时，明确写成
"yes"、"off"或其他带引号的值。 - 需要数字时，确认目标程序是否要求数字类型；不要仅凭 YAML 校验通过就把
"443"当成443。 - 需要日期、布尔值或空值时，查看目标客户端、部署工具或 schema 的官方定义。
- 修改后重新执行语法校验，再执行目标平台自己的配置检查或启动测试。
本地校验：优先使用 yamllint，不上传真实配置
如果配置中包含订阅地址、账号、密钥或内部域名，建议在本地检查。yamllint 官方文档说明，它不仅检查语法，还可以检查重复键、缩进、尾随空格等问题；安装和基本用法可参考yamllint 官方 Quickstart。
- 安装：在支持 pip 的环境执行
python -m pip install --user yamllint；也可以按系统使用官方文档中的包管理器命令。 - 检查文件：执行
yamllint config.yml，把config.yml替换为实际文件名。 - 检查目录：执行
yamllint .，适合排查项目中多个 YAML 文件。 - 根据输出中的文件名、行号、列号定位，不要一次改动整份文件。
- 修复后再次运行命令；若 yamllint 通过但客户端仍拒绝，转入 schema、必填字段、版本和权限排查。
若只想验证是否能被 Python 安全加载，可在本地使用 PyYAML 的 safe_load；官方文档说明该方法只识别标准 YAML 标签，不构造任意 Python 对象。但它仍不能替代目标平台的 schema 校验。
python -c "import sys,yaml; yaml.safe_load(open(sys.argv[1], encoding='utf-8')); print('YAML parse OK')" config.yml
如果命令报模块不存在，先安装对应依赖；如果文件编码、文档流或自定义标签不符合目标工具要求，仍应以目标工具的官方解析器和日志为准。
语法校验通过后，继续按这个顺序排查
- 确认文件来源：判断当前文件是手写配置、模板生成文件，还是客户端导出的文件；不同来源可能使用不同字段和 schema。
- 确认版本：查看目标客户端或部署工具当前支持的配置版本，删除已废弃字段，避免把旧版本示例直接套用。
- 确认必填字段：逐项对照目标平台官方配置说明，检查字段名大小写、嵌套层级和数据类型。
- 确认引用资源：检查规则集、证书、脚本或外部文件路径是否存在；路径错误不属于 YAML 语法错误。
- 读取完整日志：区分“解析失败”“字段未知”“值类型错误”“文件权限不足”和“网络资源不可达”，每次只修改一个因素。
- 回滚：保留修复前的脱敏副本；如果修改后出现新的错误，恢复到最后一个能解析的版本再逐项改动。
对代理客户端配置而言，语法校验只回答“文件能不能被 YAML 读取”，不会自动证明节点、策略组、规则、DNS 或本地权限都能正常工作。遇到导入失败，可继续参考站内的YAML 语法检查和配置文件解析失败排查页面。
修复完成后的自查清单
- 已删除或转换所有用于缩进的 Tab。
- 同级键的缩进一致，列表层级清楚。
- 冒号、短横线、括号和引号均符合结构要求。
- 没有重复键，或已确认重复键符合目标工具的明确行为。
- 包含
#、:、{}、[]的文本已按需要加引号。 - 已用本地 linter 或解析器检查，真实订阅和密钥未上传到在线工具。
- 语法通过后，又检查了平台版本、schema、必填字段和运行日志。
本页只讨论 YAML 解析与配置文件排查，不代表任何客户端或服务对配置可用性作出保证。
常见问题
YAML 格式错误最常见的原因是什么？
最常见的是 Tab 与空格混用、同级缩进不一致、冒号或短横线写法错误、引号未闭合，以及把包含特殊字符的文本直接写成普通值。先检查报错行前后几行，不要只盯着报错行。
YAML 一定要使用 2 个空格缩进吗？
不一定。YAML 规范依靠缩进表达层级，具体缩进宽度可以因文件约定而不同；关键是同一文件保持一致，并符合目标解析器和项目规范。yamllint 可以配置固定空格数或要求缩进一致。
YAML 校验通过后，为什么客户端仍然报错？
语法校验只说明文件可以被 YAML 解析，不代表字段、版本、数据类型、必填项、路径或权限符合客户端要求。下一步应查看目标客户端日志，并对照其官方配置说明做 schema 和运行级检查。
YAML 中的 yes、no、on、off 要不要加引号？
如果它们代表普通字符串，建议加引号，避免不同 YAML 版本或解析器按布尔值解析。YAML 1.1 与 1.2 的类型解析存在差异，最终应以目标工具使用的 schema 和官方说明为准。
包含订阅链接或密钥的 YAML 能否粘贴到在线校验器？
不建议。先删除订阅地址、账号、密钥、令牌、内网域名和证书内容，再使用脱敏副本；更稳妥的做法是在本地使用 yamllint 或本地 YAML 解析器检查。