← 全部文章
更新於 May 29, 20266 min read

YAML 格式化器:格式化、重新縮排與驗證 YAML

YAML 格式化器會重新縮排並正規化 YAML,讓它既可讀又便於 diff。學習縮排規則、型別陷阱,以及何時要格式化、何時要轉成 JSON。

YAML 是空白敏感的，所以一個誤入的 tab 或不一致的縮排不只看起來雜亂 —— 它會改變語意，甚至讓解析直接失敗。一個 YAML formatter 能修好這件事：它把你的 YAML 重新縮排到一致的深度、規範化空白，並（可選地）排序 key，讓檔案可讀、diff 也乾淨。本指南說明 YAML formatter 做什麼、它強制哪些縮排規則、需留意的型別陷阱，以及什麼時候該格式化 YAML、什麼時候該把它轉成 JSON。

YAML Formatter 做什麼

formatter 把你的 YAML 解析成資料結構，再用一致的風格重新序列化。資料不變 —— 只是呈現方式被規範化：

  • 重新縮排 每一層都改成固定寬度（常見是 2 空白），並把 tab 換成空白
  • 規範化空白：冒號周圍、清單 dash 周圍、行內集合周圍
  • 可選地排序 key，得到一個 canonical、利於 diff 的順序
  • 順便驗證 —— 解析不過就代表你有語法錯誤要先修
# 之前 —— 縮排混亂，難掃讀
server:
    host: api.example.com
    ports:
    - 8080
    - 8443
database: {name: mydb, pool: 5}

# 之後 —— 2 空白縮排，規範化
server:
  host: api.example.com
  ports:
    - 8080
    - 8443
database:
  name: mydb
  pool: 5

為什麼要格式化 YAML

  • 可讀性 —— CI pipeline、Kubernetes manifest 與 Docker Compose 檔案都會深深巢狀；一致的縮排讓它們好掃讀。
  • 乾淨的 diff 與 review —— 規範化的格式（加上排序 key）讓 PR 只顯示真正的變更，而不是空白雜訊。
  • 及早抓到錯誤 —— 只有合法 YAML 才能被成功格式化，所以 formatter 順便就是一次快速合法性檢查。
  • 團隊風格一致 —— 一套風格自動套用，而不是每位作者各自的縮排習慣。

Formatter 強制的縮排規則

YAML 多數錯誤都是縮排錯誤，而 formatter 正是把這些標準化的：

  • 只用空白 —— 絕不要用 tab。 YAML 禁止用 tab 字元做縮排。一個 tab 是最常見的「為什麼解析不過？」YAML bug。
  • 深度一致。 同層的 key 相對父節點必須縮排相同的空白數。formatter 會把一切都改寫到一個固定寬度。
  • 清單對齊。 區塊序列（-）裡的元素要對齊在 key 之下；formatter 會規範化 dash 是縮排還是齊平。

重新格式化時的型別陷阱

格式化保留資料，但當值沒加引號時，YAML 的型別推論還是可能讓你大吃一驚 —— 在你完全信任輸出前值得了解：

  • 「Norway problem」。 沒加引號的 NO、yes、 on、off 可能被讀成布林值，於是國家代碼 NO 就變成了 false。這類值要加引號，讓它們保持字串。
  • 前置零與大數字。007 如果被當成數字讀就會掉前置零；非常大的整數會失去精度。需要保持字串的 ID 要加引號。
  • 日期與時間戳。 某些 parser 會把沒引號、像日期的字串強轉成時間戳型別。若你需要字面字串就加上引號。

Block 風格 vs Flow 風格

YAML 有兩種寫集合的方法：block（縮排、行導向）與 flow（行內、類似 JSON，使用 [] / {}）：

# block
ports:
  - 80
  - 443

# flow（相同資料）
ports: [80, 443]

formatter 通常為了可讀性會統一成 block 風格。flow 風格相容 JSON —— 在只吃 JSON 的工具鏈裡嵌入 YAML 時很有用 —— 但層級一深就難掃讀。

錨點與別名：可重用片段

& 標記一個 anchor；* 引用它。在不複製貼上的前提下於多個服務間共用設定時很有用，formatter 會保留它們：

defaults: &defaults
  retries: 3
  timeout: 30
api:
  <<: *defaults
  url: https://api.example.com
worker:
  <<: *defaults
  url: https://worker.example.com

注意：把 YAML 轉成 JSON 時，anchor 與 alias 會 消失 —— JSON 沒有參考型別，所以這些值會被內聯展開。YAML → JSON → YAML 來回轉一圈就丟了。

超越解析的 Lint：yamllint

formatter 規範形狀；yamllint 強制風格規範（行長、key 順序、文件起始標記、truthy 值、註解間距）。在 CI 裡把它們搭配：先 format，再用團隊挑的規則 lint。

格式化 YAML 還是轉成 JSON

格式化讓檔案保持 YAML —— 適合人們還會繼續編輯的情況。轉成 JSON 是為了程式消費它（多數應用執行期只解析 JSON）。由於 YAML 1.2 是 JSON 的嚴格超集，在資料上是無損轉換；見 把 YAML 轉成 JSON 與 JSON vs YAML，了解什麼時候用哪一個。

在瀏覽器裡格式化與驗證 YAML

把你的 YAML 貼到 fixjson 的 YAML 驗證器與格式化工具，按 Format YAML 來重新縮排與規範化，或按 To JSON 轉成 JSON。它會回報任何語法錯誤的精確行號，而且一切都在你的瀏覽器裡跑 —— 不上傳 —— 對含主機名、密碼或內部設定的設定檔尤其重要。

常見問題

YAML formatter 做什麼？

它把你的 YAML 解析後再以一致的縮排與空白（可選還排序 key）重新序列化，讓檔案可讀、對 diff 友善。資料不變 —— 只是格式被規範化。

為什麼我的 YAML 解析失敗？

幾乎總是縮排：一個 tab 字元（YAML 禁止 tab 縮排），或同層 key 縮排深度不一致。formatter 會把一切改寫到一個基於空白的固定寬度，能暴露並修掉大多數這類問題。

格式化 YAML 會改變我的資料嗎？

不會 —— 它只改空白與 key 順序。但要留意沒引號的值：YAML 可能會做型別推論（「Norway problem」），所以像 NO 或 007 這類必須保留字串的值要加引號。

我該格式化 YAML 還是轉成 JSON？

需要繼續給人編輯就格式化；需要程式消費就轉 JSON。很多團隊用 YAML 撰寫，並在載入時轉成 JSON。

相關工具與指南