CSV 和 JSON 擅長的場景不同

CSV 是簡單的表格格式,適合用試算表開啟,也常用於大量匯入。
JSON 則適合 API 回應、設定資料、陣列與巢狀物件等結構化資料。

CSV 與 JSON 轉換:API 串接與資料移轉的格式選擇

能夠在兩者之間轉換,可以讓團隊交接、後台批次匯入、API 測試資料準備變得更順。

CSV 轉 JSON 時的重點

使用標題列作為 key

許多 CSV 的第一列會是 name,email,role 這類標題。
轉成 JSON 時,通常會把這些標題當成物件的 key。

[
  { "name": "Alice", "email": "alice@example.com", "role": "admin" }
]

確認分隔符號

不是所有類似 CSV 的檔案都使用逗號分隔。
有些匯出資料會使用 Tab 或分號。
如果欄位沒有正確切開,請先確認分隔符號設定。

注意值的型別

CSV 裡的值通常看起來都是文字。
轉成 JSON 後,要確認 ID、郵遞區號、電話號碼這類看似數字的值,是否應該保留為字串。

JSON 轉 CSV 時的重點

當 JSON 是一組具有相似 key 的物件陣列時,最容易轉成 CSV。
如果資料中有巢狀物件或陣列,就需要決定要用 profile.name 這類 key 攤平、序列化到單一儲存格,或排除不適合表格的欄位。

對試算表與批次匯入而言,穩定、清楚的欄位通常比完整保留所有巢狀結構更實用。

範例:把物件陣列轉成 CSV

有像這樣的 JSON 時,

[
  { "id": 1, "name": "Alice", "role": "admin" },
  { "id": 2, "name": "Bob", "role": "member" }
]

只要所有物件都有相同的鍵,把鍵對應到標題列、值對應到各列,就能得到 CSV。

id,name,role
1,Alice,admin
2,Bob,member

反過來,如果每個物件的鍵不一致(例如有的沒有 role),欄位就會錯位。轉成 CSV 之前,先確認「所有紀錄是否為相同形狀」,就能避免出錯。

跳脫與字元編碼的陷阱

CSV 看起來單純,也因此容易依值的內容而壞掉。實務上容易絆倒的有以下兩點。

含有逗號、換行或引號的值

如果值本身含有逗號或換行,除非用引號包住來跳脫,否則欄位會錯位。RFC 4180 規定把值包在 "..." 中,值裡面的 " 則寫成兩個 ""。

id,note
1,"Hello, world"
2,"跨兩行的
備註"
3,"他說了""了解"""

請確認轉換工具或函式庫是否會自動進行這種跳脫。若是手動拼接字串,幾乎一定會踩到這個陷阱。

字元編碼與 BOM

用 Excel 開啟含有中文或日文的 CSV,有時會變成亂碼。這是因為 Excel 把 UTF-8 誤認為其他編碼,以 UTF-8(含 BOM) 輸出,在許多環境中就能正確開啟。反過來,以程式讀取的一方若不移除 BOM,第一個鍵可能會錯位,請依用途區分使用。

使用 DevToolKits 轉換

CSV ⇔ JSON 轉換工具 支援雙向轉換,也能調整分隔符號與標題列設定。
轉換後可以用 JSON 格式化工具 檢查結構,或透過 JSON ⇔ YAML 轉換工具 轉成設定檔格式。

常見問題

CSV 的數字在 JSON 中被自動變成數值,怎麼辦?

像郵遞區號、ID、電話號碼這類「看似數字但應視為字串」的值,若被轉成數值可能會掉開頭的 0 或溢位。轉換時若有「視為字串」的選項就使用它,沒有的話請在轉換後確認並修正這些欄位的型別。

巢狀的 JSON 可以轉成 CSV 嗎?

CSV 是扁平的表格格式,巢狀的物件或陣列無法直接塞進單一儲存格。請用 profile.name 這類 key 攤平,或只取需要的欄位再轉成 CSV,較容易處理。

明明是逗號分隔,欄位卻錯位了。

若值中含有逗號或換行,除非以包圍引號("...")正確逸脫,否則欄位會錯位。此外,名為「CSV」的檔案也可能是 Tab 或分號分隔。請確認分隔符號與引號設定。

用 Excel 開啟時,中文會變成亂碼。

Excel 可能把 UTF-8 的 CSV 誤認為其他編碼,導致文字亂碼。改以 UTF-8(含 BOM) 重新儲存,在許多環境中就能正確顯示。反過來,以程式讀取時,BOM 可能被當成多餘字元混入,請在讀取端移除 BOM。

可以把鍵不一致的 JSON 轉成 CSV 嗎?

當各紀錄的鍵不同時,可以把所有鍵的聯集作為標題列,並把不存在的值留空,合併成一份 CSV。不過欄位會增加而變得難以閱讀,因此建議事先統一資料的形狀,或只保留需要的欄位。