YAML 講解 + JSON vs. YAML

如果你編輯過 Docker Compose、GitHub Actions、Kubernetes 這類現代工具的設定檔，你就已經寫過 YAML 了。它被設計成對人最易讀的資料格式，但這份易讀也帶著幾處鋒利的邊角。本指南講解 YAML 如何運作、要留意的陷阱，以及它與 JSON 如何對比。

YAML 是什麼

YAML（“YAML Ain’t Markup Language”）是一種資料格式，表示的東西與 JSON 相同 —— 鍵/值對、清單和巢狀結構 —— 但其語法為方便人手寫手讀而調校。它成為設定檔的首選，正是因為一眼就能掃讀。

name: RunWebTools
active: true
tags:
  - json
  - free
address:
  city: London
  postcode: null

語法如何運作

三個概念涵蓋了 YAML 的大部分：

• 縮排表示結構。 巢狀用空格表達，而非大括號。同一縮排層級的項目彼此是兄弟。
• 鍵/值對 用 key: value（冒號後的空格是必需的）。
• 清單 在每項前用一個 -。

那些陷阱

用空格，絕不用 Tab

YAML 禁止用 Tab 字元縮排 —— 它會導致剖析錯誤。請把編輯器設定為插入空格，因為兩者在螢幕上看著一模一樣，卻只有一個有效。

“挪威問題”

YAML 會嘗試猜測型別，這偶爾會適得其反。不加引號的 no、yes、on、off 會變成布林值 —— 眾所周知，挪威的國家代碼 NO 會變成 false。當你指的是字面字串時，請加引號："NO"。

縮排錯誤悄無聲息

因為空白帶有含義，單獨一行錯位就能在沒有任何錯誤的情況下改變結構 —— 檔案只是被剖析成了你並不想要的東西。把它交給一個會把剖析結果重新輸出的 YAML 驗證器，是看清 YAML 究竟理解了什麼的最快辦法。

YAML vs. JSON

兩者能表示相同的資料 —— 事實上，所有有效的 JSON 也都是有效的 YAML。取捨在於：

• 可讀性： 對人而言 YAML 勝出 —— 沒有大括號或引號，還支援註解（#），而 JSON 不支援。
• 嚴格性： 對機器而言 JSON 勝出 —— 它剛性的語法幾乎不給 YAML 所允許的型別猜測和縮排意外留下空間。
• 用途： 給人編輯的檔案（設定）選 YAML，給程式交換的資料（API）選 JSON。

需要在兩者之間轉換？用 YAML 格式化器 和 JSON 格式化器 就能格式化並檢查任一種。若你覺得 YAML 彆扭，我們關於 JSON 及其常見錯誤 的指南是很好的搭配閱讀。