JSON 轉 Markdown 表格：陣列、API 回應、巢狀資料的完整轉換

當你需要把手上的 JSON 物件陣列變成 Markdown 表格時，最不容易出錯的路徑是：先轉成 CSV，再貼到 CSV 轉 Markdown 工具裡。直接做 JSON 轉表格的工具當然有，但一旦資料裡混進巢狀結構或缺漏的鍵，結果就容易斷裂，而且要花很多時間追查是哪一列出了問題。中間放一道 CSV，欄位與行的對應關係就能用眼睛確認，結果自然穩定。

這篇文章從確認 JSON 結構開始，帶你走過 CSV 轉換、Markdown 表格生成、API 回應處理、巢狀 JSON 扁平化的完整流程。所有操作都在瀏覽器裡完成，就算你貼的是 API 回應或公司內部資料，也不會傳到任何外部伺服器。

結論：JSON 經 CSV 轉 Markdown 表格

先把整個流程攤開看。

用 JSON Formatter 格式化 JSON，確認它是物件陣列
把陣列轉成 CSV（每個物件的鍵變成欄位標題，每個元素變成一列）
將 CSV 貼到 CSV 轉 Markdown 生成表格

FormatArc 沒有「一鍵 JSON 轉表格」的按鈕。取而代之的是格式化工具加 CSV 轉換工具的搭配，可以在任何環境產出不會斷裂的 GFM（GitHub Flavored Markdown）相容表格。CSV 作為中間格式的價值在於：欄位對不齊、值缺漏這些問題，你可以當場發現當場修。

適合轉 Markdown 表格的 JSON 結構

Markdown 表格是「欄位標題列 + 資料列」的二維結構。所以最適合轉表格的 JSON，是結構相同的物件排成陣列。

[
  { "name": "Mika", "role": "admin", "active": true },
  { "name": "Noah", "role": "viewer", "active": false }
]

每個物件的鍵（name、role、active）對應欄位標題，陣列的每個元素對應一列。上面的 JSON 對應的表格如下：

| name | role | active |
| --- | --- | --- |
| Mika | admin | true |
| Noah | viewer | false |

反過來說，沒被陣列包住的單一物件（{ ... }）本身不會變成多列。你可以把它做成鍵值兩欄的表格，或者先用 [ { ... } ] 包成陣列再轉。

步驟：JSON 轉 Markdown 表格

步驟 1：格式化 JSON 並確認結構

從 API 回應或日誌檔抓出來的 JSON，常常是一整行沒有換行的字串。先把內容貼到 JSON Formatter 做格式化，然後用眼睛確認：它真的是物件陣列嗎？每個元素都有相同的鍵嗎？

如果有語法錯誤（SyntaxError），後續轉換一定會失敗。檢查是否有漏掉的右括號或多餘的尾隨逗號（trailing comma）。// 開頭的註解在標準 JSON 中不被允許，需要先去掉。

步驟 2：將陣列轉為 CSV

結構確認沒問題後，把陣列重組成 CSV。要做的事情只有兩件：

第一列寫物件的鍵，用逗號分隔，作為標題列
每個物件的值按相同順序用逗號分隔，一列一列寫

上面那個 JSON 轉出來就是：

name,role,active
Mika,admin,true
Noah,viewer,false

如果值裡面有逗號（,）或換行符號，就用雙引號（"..."）把那個值包起來。CSV 中有逗號或換行的值，CSV 轉 Markdown 會自動處理，不需要你手動 escape。

步驟 3：用 CSV 轉 Markdown 生成表格

CSV 準備好之後，貼到 CSV 轉 Markdown 執行。

CSV 轉 Markdown 表格的轉換結果

右側會立刻輸出 GFM 相容的 Markdown 表格。分隔線和欄寬自動對齊，直接複製就能貼進 GitHub README、Issue、PR 說明或技術文檔。

API 回應 JSON 轉表格

用 curl 呼叫 API 之後，想把回應整理成表格分享，是很常見的場景。流程跟上面一樣：先把回應格式化，再經 CSV 轉表格。

curl -s https://api.example.com/users | jq .

如果回應本身就是物件陣列，直接貼到 JSON Formatter 格式化後進入步驟 2 即可。如果回應結構是 { "data": [ ... ] } 這種把陣列包在裡面的形式，就只抽取你要轉表格的陣列部分（data 的內容）。用 jq 的話，jq '.data' 就能單獨取出陣列。

如果回應裡有認證標頭（Bearer token）或分頁（pagination），需要多一步把多頁資料合併成一個完整陣列，再走同樣的 CSV 流程。

巢狀 JSON 怎麼處理

實際的 API 回應中，值裡面再套物件或陣列的情況非常普遍。

[
  { "name": "Mika", "address": { "city": "Tokyo", "zip": "100-0001" } }
]

Markdown 表格是二維的平面結構，沒辦法把巢狀結構原封不動塞進儲存格。處理方向有兩種。

先扁平化再轉表格

把巢狀鍵展開成 address.city 這種點號記法（dot notation），轉成一維結構後再做 CSV。

name,address.city,address.zip
Mika,Tokyo,100-0001

資料量少時手動拆也可以，但資料量一多就容易漏。用 jq 的 to_entries 或 Python 的 pandas.json_normalize() 做自動扁平化比較保險。扁平化之後，照樣走 CSV 到 CSV 轉 Markdown 的路徑。

巢狀值以字串形式放入儲存格

不做扁平化，把巢狀的物件整段序列化成 JSON 字串，塞進一個儲存格。比如 address 欄位的值直接寫成 {"city":"Tokyo","zip":"100-0001"}。

這種寫法要注意：字串裡面如果有管線符號（|）或換行，表格結構就會斷。在 CSV 階段用雙引號把值包起來，CSV 轉 Markdown 會自動對儲存格內的管線符號做反斜線 escape（\|），換行則替換成空格。

指定欄位對齊方式

GFM 表格可以在分隔列加冒號（:）來控制每個欄位的對齊。

| name | count |
| :--- | ---: |
| Mika | 12 |
| Noah | 340 |

:--- — 左對齊（預設）
:---: — 置中對齊
---: — 右對齊

數字欄位用右對齊，個位數就能對齊，讀起來整齊。對齊記號在 GitHub 等 GFM 渲染器中都能正常運作，但不同平台的渲染結果可能略有差異。

常見問題與注意事項

各元素的鍵不一致

陣列中每個物件包含的鍵不相同時，要先決定表格要出哪些欄位。取所有物件鍵的並集，缺值的儲存格就是空白；只取第一個物件的鍵，後面才出現的鍵就會被漏掉。在組 CSV 的階段就把欄位對齊方式定下來，產出才會穩定。

布林值、null、數字的處理

true、false、null 和數字寫進 CSV 後就是純文字。Markdown 表格中也是以字串形式顯示，語義不會丟失。空值會變成空儲存格。

儲存格內的換行與管線字元

值裡面如果包含換行或管線符號（|），會跟欄位分隔符衝突，表格就會斷掉。在 CSV 階段用雙引號把值包起來，CSV 轉 Markdown 會安全處理換行和管線字元。

常見問答

需要把 JSON 上傳到伺服器嗎？

不需要。FormatArc 的所有轉換都在你的瀏覽器本地執行。無論你貼的是 API 回應、公司內部資料還是包含個人資料的 JSON，都不會傳送到外部伺服器。

為什麼要經 CSV 而不直接轉？

CSV 作為中間格式，讓欄位標題與每列資料的對應關係可以被眼睛看到。JSON 直接轉表格時，巢狀或缺漏鍵導致結果斷裂後，要追查原因很費事。中間放一道 CSV，哪一列對不齊、哪個值缺了，當場就能修。

巢狀 JSON 能直接變成表格嗎？

不能。要用 address.city 這種點號記法做扁平化，或者把巢狀部分序列化成 JSON 字串塞進單一儲存格。具體步驟見上方「巢狀 JSON 怎麼處理」一節。

用程式將 JSON 轉 Markdown 表格

如果你需要在腳本、CI 管線或文件自動生成流程中做這個轉換，而不是開瀏覽器操作，以下幾個方案可以直接用。

Python（tabulate）

from tabulate import tabulate

data = [
    {"id": 1, "name": "Mika",  "role": "admin"},
    {"id": 2, "name": "Noah",  "role": "viewer"},
    {"id": 3, "name": "Sofia", "role": "editor"},
]
print(tabulate(data, headers="keys", tablefmt="pipe"))

tablefmt="pipe" 輸出 GFM 管線表格。需要顯式寫出對齊列的話用 tablefmt="github"。安裝：pip install tabulate。

JavaScript / Node.js（tablemark）

import tablemark from "tablemark";

const data = [
  { id: 1, name: "Mika",  role: "admin" },
  { id: 2, name: "Noah",  role: "viewer" },
  { id: 3, name: "Sofia", role: "editor" },
];
console.log(tablemark(data));

tablemark 直接接收物件陣列，輸出 GFM 管線表格。安裝：npm install tablemark。

Shell（jq + FormatArc CLI）

不想裝 runtime 依賴、一行搞定：用 jq 產生 CSV，再 pipe 給 formatarc CLI。

curl -s https://api.example.com/users \
  | jq -r '(.[0] | keys_unsorted) as $k | $k, (.[] | [.[$k[]]]) | @csv' \
  | npx formatarc csv-to-markdown

jq 把第一個物件的鍵抽出作為標題列，其餘資料以 CSV 格式輸出。formatarc csv-to-markdown 從 stdin 讀 CSV，把 Markdown 表格寫到 stdout。在 CI 環境或 Makefile 中從 API 回應自動再生 README 表格時很好用。

Markdown 表格的侷限與 HTML 的切換判斷

Markdown 表格的語法本來就刻意保持簡單。當你的資料超出這個格式能表達的範圍時，不要硬拗，直接在 Markdown 裡切換成 HTML <table>。

需求	Markdown 表格	HTML `<table>`	建議
儲存格合併（`colspan` / `rowspan`）	不支援	支援	HTML
儲存格內換行	用內嵌 `<br>`	`<br>` 原生支援	HTML 或內嵌 `<br>`
100 列以上大量資料	取決於渲染器	輕量	HTML 或分頁
餵給 LLM 的 prompt 上下文	最佳（token 效率高）	標籤冗長	Markdown
GitHub README 顯示	最佳	取決於渲染器	Markdown
左／中／右以外的對齊	不支援	inline style 可達成	HTML
無標題列的表格	不合標準（仍需分隔列）	支援	HTML

GitHub、Obsidian、Notion（block import）以及大多數靜態網站產生器都接受 Markdown 中的原生 HTML 標籤。如果需要儲存格合併或可排序的標題列，手寫 <table> 區塊，或用模板工具從 JSON 產生後直接嵌入。反方向——把複雜的 HTML 表格轉回 Markdown 表格——則可以在格式約束放寬後再用轉換工具處理。

總結

把 JSON 變成整齊的 Markdown 表格，最可靠的路徑就是經 CSV 中繼。用 JSON Formatter 確認結構，把陣列整理成 CSV，貼到 CSV 轉 Markdown 執行，就能直接複製 GFM 相容表格。巢狀 JSON、複雜 API 回應這些不那麼直線的情況，加一道扁平化步驟後同樣可以走通。

生成好的 Markdown 表格如果要餵給 LLM 當上下文，Markdown 的 token 效率比 HTML 表格好很多，標籤少、結構乾淨，資料擷取精確度也更高。