JSON 转 Markdown 表格:把接口数据贴进文档的最短路径

写文档、写 Pull Request、写 GitHub Issue 的时候,经常手里攥着一段 JSON 数组,想让别人不用翻原始数据就看懂。直接贴个代码块,评审还得在脑子里把每个字段对位;贴进电子表格再导出,又要绕一大圈。最干净的做法是把这组对象转成 Markdown 竖线表格,一行一条记录,列就是字段名。

JSON 数组转表格的核心:对象 key 做表头

转换的规则其实只有一条:读数组里每个对象,把所有键的并集按第一次出现的顺序排成表头,每个对象输出一行。

并集这一点很关键。假设你的数据里前几条记录有 team 字段、后几条没有,工具不会因为某条缺字段就把这一列丢掉,而是让 team 照样占一列,缺的那条在对应位置补一个空单元格。这样形状不齐的数据也能对齐。一个最小例子:[{"a":1,"b":2},{"a":3}] 会生成两列 a 和 b,第二行 b 下面是空格,而不是漏列。

一段真实输入输出

把这段 JSON 粘进 JSON 转 Markdown 表格工具:

[
  {"name": "李雷", "role": "组长", "team": "前端三组"},
  {"name": "韩梅梅", "role": "维护"}
]

得到的是这样一张可直接复制的表格:

| name | role | team |
| :--- | :--- | :--- |
| 李雷 | 组长 | 前端三组 |
| 韩梅梅 | 维护 |  |

team 因为第一条记录里出现过,就成了第三列;第二条没有这个字段,在那一格留空。复制进 README 或 Issue,渲染出来就是一张整齐的网格。

对齐分隔符:左中右一行决定

Markdown 靠表头下面那行分隔符决定整列怎么对齐。规则是:

• 左对齐写成 :---
• 居中写成 :---:
• 右对齐写成 ---:

数字列选居中或右对齐,读起来更舒服。工具里选左、中、右,这行分隔符会跟着变,不用自己记冒号放哪边。这是一个设置管所有列,覆盖最常见的整表统一对齐场景。

竖线和换行:不转义就错位

表格里最容易踩的坑是单元格里本身带竖线。值里一个裸竖线会提前结束这个单元格,把后面所有列顶错位。比如命令字符串 cat file | grep error,不处理的话整行就乱了。

正确做法是写这一行之前先把竖线转义成反斜杠竖线,输出成 cat file \| grep error,渲染时还是一个完整单元格。反斜杠本身也要转义,所以 Windows 路径不会出问题。换行也类似:值里的换行可以压成空格,也可以保留成 <br> 标签,看你想要单行还是想保留多行结构。

嵌套字段:序列化进一个单元格

如果某个字段的值是嵌套对象或数组,直接打印很容易变成没法读的 object Object。合理的处理是把它转回紧凑 JSON 塞进一个单元格,{"k":"v"} 就显示成 {"k":"v"},列表显示成 ["x","y"],结构看得见、复制也准。

要是你确实想让 addr.city 和 addr.zip 各占一列,得先把 JSON 拍平再转换,这一步工具不会替你做。常见的另一个误区是数组末尾留了多余逗号,[{...},] 这种 JSON 不合法,解析器会直接报错,删掉最后那个逗号就好。

我自己怎么用它

我带前端三组,平时整理组员日报、汇总接口字段的时候用得最多。以前贴接口返回都是整段 JSON 甩进群里,经常有人问哪个字段是哪个意思。改成先转成 Markdown 表格再贴,字段名当表头一目了然,缺字段的记录也能看出来是哪条没填全。一次转换省下来回解释的好几轮,这是我把它放进日常流程的原因。

如果你的源数据是 CSV 而不是 JSON,可以用 CSV 转 Markdown 表格;手里没有现成数据、想从零敲一张表,用 Markdown 表格生成器;只是想先把 JSON 格式化看清楚结构,用 JSON 格式化工具。这几个工具都是浏览器本地运行,数据不上传。

---

Made by Toolora · Updated 2026-06-13