JSON 與 YAML:兩大關鍵資料格式

在現代開發中,資料的儲存與傳輸主要使用 JSON 與 YAML。這兩者各有所長,適用於不同的場景。

JSON 與 YAML 的轉換及其適用場景

JSON (JavaScript Object Notation)

  • 特點:輕量且解析速度快。與 JavaScript 具有極高的親和性。
  • 用途:Web API (REST)、前端的請求/回應通訊。
  • 弱點:不支援註解(Comment)。對於結尾逗號(Trailing Comma)的要求非常嚴格。

YAML (YAML Ain’t Markup Language)

  • 特點:人類可讀性極高(Human-readable)。
  • 用途:設定檔(Docker, Kubernetes, GitHub Actions)、CI/CD 流程。
  • 弱點:對於縮排(空白字元)的控制非常嚴格。相較於 JSON,其解析邏輯較為複雜。

需要相互轉換的情況

  • 編輯設定檔:當您想要將從 API 取得的 JSON 設定轉換為易於閱讀的 YAML 格式,以便在本地端進行編輯時。
  • 資料導入:為了可讀性而使用 YAML 管理設定,但為了讓程式處理而需要轉換為 JSON 格式並透過 API 發送時。
  • 除錯(Debug):想將壓縮成一行的難讀 JSON 轉換為 YAML,以便快速掌握其資料結構時。

範例:用 YAML 審閱 API 設定

假設你從 API 收到下面這份 JSON 設定。

{
  "retries": 3,
  "timeoutMs": 30000,
  "features": {
    "csvExport": true,
    "betaDashboard": false
  }
}

審閱時轉成 YAML,可以讓設定的層級更易讀。

retries: 3
timeoutMs: 30000
features:
  csvExport: true
  betaDashboard: false

這種形式下,更容易確認逾時是否以毫秒為單位、功能旗標位於哪一層。

JSON 與 YAML 對照速查表

面向 JSON YAML
易讀性 符號較多 以縮排為主,易讀
註解 不可 可用 # 撰寫
結尾逗號 不可(會出錯) 根本不需要逗號
多行字串 以 \n 跳脫 |(保留換行)/>(折疊)
主要用途 Web API、資料傳輸 設定檔、CI/CD
解析的嚴格度 語法嚴格,歧義少 依賴縮排,容易壞掉

JSON 與 YAML 的子集合關係相近,合法的 JSON 大致也能被解讀為合法的 YAML。這就是兩者能順暢互相轉換的原因。

YAML 特有的陷阱

YAML 雖然「對人友善」,卻很容易被隱含的型別轉換絆倒。撰寫設定檔時請留意以下幾點。

  • 變成布林值的字串:yes / no / on / off 若沒有加引號,可能被當成布林值(也就是所謂的「Norway problem」:國碼 NO 變成 false)。想當成字串時,請像 "no" 這樣明確標示。
  • 開頭的 0 與版本號:08 可能被當成八進位而出錯,1.20 可能被四捨五入成數字 1.2。版本與郵遞區號請像 "1.20" 這樣加上引號。
  • 縮排不能使用 Tab:YAML 只能用半形空白。混入 Tab 會造成解析錯誤。

拿不定主意時,先轉成 JSON 一次,就能看清是字串還是數字,進而發現這些隱含的轉換。

在 DevToolKits 進行無縫轉換

使用 JSON ⇔ YAML 轉換工具,只需單擊一下即可在兩種格式之間進行雙向轉換。貼上 JSON 即可輸出 YAML,貼上 YAML 即可輸出 JSON,非常簡單。

💡 注意事項:由於 JSON 不支援註解,從 YAML 轉換為 JSON 時,原有的註解將會消失。因此,此工具最適合用於純資料結構的轉換。

2026 年 11 月新增的功能

  • TOML ⇄ JSON / YAML:可將 Cargo.toml、pyproject.toml 等 TOML 轉成 JSON 或 YAML,也可反向轉換。TOML 沒有 null 且最上層必須是表,遇到時會指出問題位置。
  • XML ⇄ JSON:屬性成為 @名稱,文字成為 #text,重複的元素成為陣列。語法錯誤會附上行與欄。

在工具中試用

常見問題

JSON 與 YAML 該用哪一個?

機器之間的通訊(Web API)適合解析快、歧義少的 JSON;人類編輯的設定檔(Docker、Kubernetes、CI/CD)適合可寫註解且易讀的 YAML。由於兩者可互轉,依用途分開使用是基本原則。

轉換 YAML 後註解不見了。

JSON 沒有註解的概念,因此 YAML → JSON → YAML 來回轉換會遺失註解。想保留註解的設定檔,請在轉換後手動補回,或只用於純資料結構的轉換。

YAML 縮排出現錯誤。

YAML 對空白縮排很嚴格,且不能使用 Tab 字元。層級錯位會導致解析錯誤或非預期的結構。先轉成 JSON 確認結構,再轉回 YAML,較容易找出縮排的問題。

no 或 1.20 變成了非預期的值。

YAML 會進行隱含的型別轉換,所以 yes / no / on / off 可能被解讀成布林值,1.20 可能被解讀成數字 1.2。想當成字串的值,請像 "no"、"1.20" 這樣用引號包住。轉成 JSON 就能確認實際被解讀成什麼型別。

在 YAML 中如何撰寫多行字串?

想原樣保留換行時用 |(字面區塊),想把長句適度折行並視為一行時用 >(折疊區塊)。轉成 JSON 後會變成含有 \n 的單一字串,因此能確認換行是否正確保留。