JSON、YAML、CSV、Markdown 数据格式比较速查表——按用途快速选择

JSON、YAML、CSV、Markdown 都是「用文本表达结构化数据」的格式，但它们各自解决的核心问题完全不同。配置文件里用 CSV，层级结构就没法表达；API 响应用 YAML，语法不够严格；把表格数据塞进 JSON，每行都重复键名，体积膨胀。Markdown 写给人看的文档很强，但当成机器可读的数据源就会在后面埋坑。

这篇文章是一张速查表，帮你在开项目或设计数据管道时快速判断「该用哪个格式」。从快速决策矩阵开始，依次是功能对比、注释支持、解析器生态、按用途的选择矩阵、常见踩坑、LLM 场景下的选择、以及规格信息。

快速决策矩阵——该选哪个格式

拿不准的时候先看这张表。列出常见用途和推荐格式。

一句话总结：机器之间传数据用 JSON，人手动编辑的配置用 YAML，二维表格用 CSV，人读的文档用 Markdown。其余的细枝末节在下面各节里调整。

先在浏览器里把四种格式转一遍

光看说明不如把同一份数据用四种格式写出来对比。FormatArc 的所有转换工具都在浏览器内运行，输入的数据不会发送到外部服务器。内部数据或 API 响应可以直接粘贴进去试。

• JSON 格式化工具——JSON 格式化、校验、语法错误定位
• YAML 转 JSON / JSON 转 YAML——YAML 和 JSON 互转
• CSV 转 JSON / JSON 转 CSV——表格数据和结构化 JSON 互转
• CSV 转 Markdown——电子表格转 Markdown 表格
• Markdown 转 HTML / HTML 转 Markdown——文档格式互转

对把敏感数据粘到上传型在线工具心里没底的话，可以先打码再试。粘贴敏感数据前的 5 项验证 值得先看。FormatArc 不上传、不存储，数据只在浏览器内存里存在。

本文覆盖的四种格式和未覆盖的格式

本文聚焦 JSON、YAML、CSV、Markdown 这四种。它们是 Web 开发、配置文件、数据交换、技术文档四个场景中出现频率最高的组合，也是 FormatArc 浏览器内能互转的范围。

以下格式不在本文范围内：

• XML——规格校验能力强，但语法冗长，新项目里采用率在下降。SOAP、RSS、SVG、Office Open XML 等存量系统对接时才会碰到
• TOML——Rust 的 Cargo、Python 的 pyproject.toml 等场景用的配置格式。和 YAML、JSON5 功能重叠，Web 前端领域出现频率低
• Parquet——列式二进制格式，面向大数据分析。不属于文本格式对比的范畴
• XLSX / ODS——电子表格二进制格式。本文只通过 CSV 导出/导入路径提及

如果你需要包含 XML 或 TOML 的五格式对比，网上有不少现成文章。本文的定位是把 Markdown 当一等公民的四种格式比较，贴合 2026 年写 API、配置、README、LLM prompt 的日常场景。

同一份数据用四种格式写出来

两个用户的信息（姓名、年龄、技能列表），用四种格式分别表示。同一份信息在不同格式下的结构差异一目了然。

JSON 版本

{
  "users": [
    { "name": "Alice", "age": 30, "skills": ["Python", "Go"] },
    { "name": "Bob",   "age": 25, "skills": ["JavaScript"] }
  ]
}

YAML 版本

users:
  - name: Alice
    age: 30
    skills:
      - Python
      - Go
  - name: Bob
    age: 25
    skills:
      - JavaScript

CSV 版本

CSV 没法直接表达嵌套结构，所以 skills 数组必须扁平化。常见做法有三种：用分隔符（如 ;）拼在一个单元格、展开成多列、拆成独立的表。最简单的分隔符拼接方式如下：

name,age,skills
Alice,30,Python;Go
Bob,25,JavaScript

Markdown 版本

Markdown 是文档格式而非数据交换格式，结构化表格依赖 GFM（GitHub Flavored Markdown）的表格语法。

| name  | age | skills      |
|-------|-----|-------------|
| Alice | 30  | Python, Go  |
| Bob   | 25  | JavaScript  |

同一份信息，四种形态。JSON 严格、机器友好；YAML 人读着舒服；CSV 擅长二维表格但搞不定嵌套；Markdown 渲染出来好看但别当数据源用。

四种格式的功能对比矩阵

各格式能表达什么、不能表达什么，整理成下表。

JSON 和 YAML 共享同一套数据模型（对象 + 数组 + 基本类型），所以互转非常直接。FormatArc 提供了双向转换工具，YAML 和 JSON 之间随时可以切换。YAML 和 JSON 的区别 整理了语法差异、解析器实测和选型指南。

注释支持对比

选配置文件格式时，能不能写注释是核心考量。标准规格和衍生扩展之间有差异，整理如下。

标准 JSON 不支持注释，所以配置里必须留注释的话，选 YAML、JSONC、JSON5，或者用 _comment 之类的假键来凑。JSON 注释语法与 4 种替代方案 里有更详细的说明。

各语言解析器生态对比

实际开发中，「标准库能不能直接读」「要不要装第三方库」影响很大。主要语言的现状如下。

JSON 和 CSV 在几乎所有主流语言里都有标准库支持。YAML 和 Markdown 需要第三方库，但各语言的事实标准库已经很稳定。FormatArc 把 Node.js 生态的 yaml、papaparse、marked、turndown、remark 打包进浏览器，实现无服务器的独立转换环境。

按用途的格式选择矩阵

比起抽象的对比表，按具体场景查表更快。

Markdown 表格手敲很麻烦，建议把 CSV 或 JSON 当数据源，用 FormatArc 的 CSV 转 Markdown 功能生成表格，方便后续维护。

常见的错误选择

项目里反复出现的格式选择踩坑。

用 CSV 硬塞嵌套数据

{ "user": { "address": { "city": "北京" } } } 这种层级结构塞进 CSV，你得另外定义一套扁平化规则，读数据的时候还要写一套还原逻辑。需要层级的话，一开始就选 JSON 或 YAML；或者拆成多张 CSV 表，用关系模型关联。

YAML 隐式类型转换的坑（挪威问题）

YAML 1.1 规格里，no、yes、on、off 这些字符串会被自动转成布尔值。由此引发了著名的「挪威问题」：国家代码 NO 被解析成 false。YAML 1.2 改进了部分规则，但很多解析器仍兼容 1.1 模式，所以可能被误判为布尔值的字符串，一律加引号最安全。

country: "NO"   # 安全——明确是字符串
country:  NO    # 危险——YAML 1.1 兼容解析器可能转成 false

在标准 JSON 里写注释

因为 VS Code 的 settings.json 支持注释，很多人以为标准 JSON 也能写。实际上那是 JSONC，非标准方言。标准 JSON（RFC 8259）里写注释，JSON.parse 会直接报 Unexpected token 错误。需要注释的场景，选 JSON5、JSONC 或 YAML，或者拆成单独的文件。

低估 CSV 的方言差异

RFC 4180 是参考标准，但实际工程里的 CSV 方言遍地都是。分隔符（, / \t / ;）、换行符（LF / CRLF）、引号处理、BOM（字节顺序标记）、字符编码（UTF-8 / GBK / GB18030）、有没有表头、单元格内换行怎么转义——每一项在不同解析器里行为都可能不同。「不就是个 CSV 吗」这种心态坑过的时间比 YAML 还多。上线前用样本数据把两端的解析行为都验证一遍。

把 Markdown 当机器可读的数据源

Markdown 本质是文档格式，不是设计来让机器稳定提取数据的。Markdown 表格在不同渲染器里的行为有差异，单元格里包含管道符（|）或换行时，非 GFM 渲染器直接解析失败。机器间传数据用 JSON 或 CSV，别用 Markdown。

以为 Markdown 表格是 CommonMark 标准

不是。表格语法是 GFM（GitHub Flavored Markdown）的扩展，不在 CommonMark 标准里。严格遵循 CommonMark 的渲染器会把你的表格当成普通段落渲染。GitHub、GitLab、知乎、CSDN 都支持 GFM，但内部 Wiki 或自研博客引擎不一定开了 GFM 扩展，上线前确认一下。CommonMark 与 GFM 的区别 里对比了 6 种解析器的实际渲染行为。

LLM 场景下的格式选择

给 ChatGPT、Claude、Gemini 喂上下文数据时，首选 Markdown。和 HTML 相比，去掉了冗余的标签和属性，token 消耗低，表格、列表、代码块的抽取精度也更高。LLM 输入用 Markdown 还是 HTML 有实测对比数据。

但 LLM 的结构化输出（Function Calling、JSON Mode）必须用 JSON。所以实际工程里形成了「输入用 Markdown，输出用 JSON」的不对称结构。

YAML 作为 LLM 输入输出格式有风险：缩进在 token 化过程中容易变形，加上隐式类型转换可能把字符串变成布尔值。做 LLM 输入输出格式时避开 YAML。

规格与标准历史

需要确认决策依据时查这张表。

JSON 和 CSV 的 RFC 规格很稳定。YAML 和 Markdown 则有方言分化的问题（YAML 1.1 vs 1.2；CommonMark vs GFM vs MultiMarkdown vs Pandoc），对接时要确认对方的解析器支持哪种方言。

用 FormatArc 做格式互转

四种格式之间常见的转换路径如下。FormatArc 所有工具都在浏览器内运行，数据不发送到服务器。

组合起来可以实现这样的工作流：「API 响应的 JSON 转 YAML 存为配置文件」「Excel 表格导出 CSV 再转 Markdown 表格贴进 README」「网页 HTML 转 Markdown 喂给 ChatGPT」——全部在浏览器标签页内完成，数据不出本地。

总结

拿不准时的最终检查清单：

• 机器间数据交换、API 通信：JSON
• 人手动编辑的配置文件：YAML
• 大批量二维数值/表格数据：CSV
• 人阅读的格式化文档：Markdown
• LLM 输入：Markdown；LLM 结构化输出：JSON

数据格式没有绝对的「正确」选项，只有「你最看重什么」的取舍。可读性、严格程度、解析器覆盖范围、注释支持、LLM token 效率——每个维度上四种格式各有擅长。把上面的矩阵当作一个判断参照，开新项目时用来定格式。

规格参考：

• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format在新标签页中打开
• YAML 1.2.2 Specification在新标签页中打开
• RFC 4180: Common Format and MIME Type for Comma-Separated Values (CSV) Files在新标签页中打开
• CommonMark Specification在新标签页中打开
• GitHub Flavored Markdown Spec在新标签页中打开