一份配置里加了三个短横线,转换工具突然报错,不一定说明短横线拼错了。YAML本身支持文档流,当前工具接收一份文档还是多份文档,是另一项条件。

2026年11月18日,在YAML/JSON互转工具选择“YAML → JSON”,先点“清空”,再输入:

name: alpha
---
name: beta

执行转换后,本次提示“expected a single document in the stream, but found more”,右侧没有本轮输出。

本次多文档输入被单文档转换入口拒绝,右侧结果为空
本次多文档输入被单文档转换入口拒绝,右侧结果为空

三个短横线划开的是文档边界

这里的两个name分别属于两份文档,不能因为字段名相同,就把它们理解成同一对象里的两条记录。三个短横线位于独立行,用于标记文档开始;一条YAML流可以承载多份文档,而单文档读取入口会限制这一点。

本次错误与js-yaml单文档读取接口的限制相符。它没有说明第一份里的alpha或第二份里的beta单独不能解析,也没有验证这份配置被实际部署系统读取后会有什么效果。

如果确实需要把两条记录放在一个集合里,可以在接口允许的前提下改成一个YAML序列:

- name: alpha
- name: beta
序列输入得到一个包含两项的JSON数组,结构与两份文档不同
序列输入得到一个包含两项的JSON数组,结构与两份文档不同

这轮得到一个JSON数组,里面有两个对象。它是一份文档中的一个序列,并不是把多文档模式“开好了”。

不要直接删除分隔线

对本例直接删掉三个短横线,会让两个name落到同一层映射里。重复键怎样处理取决于解析器及配置,可能报错,也可能覆盖;这都不是保留两份文档的可靠办法。

同样,把它改成数组也会改变顶层结构。某些部署格式明确要求多个独立文档,不能为了通过这个工具就把整个文件包成数组再提交。应按接收端约定使用支持多文档读取的程序,或者分别取出每份文档检查,保留原始边界和顺序。

本次为了避免把旧结果误认为新输出,测试前用工具自己的“清空”功能清除了默认内容。实际排查也应先看当前错误,再核对右侧是否属于这一轮成功转换,不能只看到一段现成JSON就认定输入已处理。

转换后至少确认顶层是对象还是数组、预期记录是否齐全。需要复习一般的双向转换操作,可参考YAML与JSON转换的结构检查,再根据接收端决定如何处理文档流。