YAML 格式化器：線上格式化、驗證與美化 YAML

YAML 1.2（2009 年）解決了最惡名昭彰的 YAML 陷阱：在 YAML 1.1 中，未加引號的 "yes"、"no"、"on"、"off"、"true" 與 "false" 被解釋為布林值。國家代碼如 "NO"（挪威）與 "YES" 會變成布林值 false 與 true——這個錯誤如此常見，以至於被稱為「挪威問題」。YAML 1.2 僅將 "true" 與 "false"（不區分大小寫）識別為布林值。我們的格式化器會偵測模糊值並建議對其加引號。

YAML 縮排黃金規則：每個巢狀層級使用 2 個空格，永遠不要使用 Tab。YAML 1.2 明確禁止使用 Tab 字元進行縮排（Tab 沒有縮排值——它們在剖析器的欄位計數器中顯示為 0）。如果您從將空格轉換為 Tab 的來源（部分聊天應用程式、網頁表單或 PDF）複製 YAML，驗證器會以確切位置標記每個 Tab。

YAML 錨點（&）與別名（*）讓您可以定義一次值並在同一文件中多次參照它。例如：`defaults: &defaults timeout: 30 retries: 3` 定義了一個錨點，而 `service_a: <<: *defaults` 將這些預設值合併到 service_a 中。這在 Docker Compose 中廣泛用於在服務間共享通用組態，在 Kubernetes 中用於減少大型清單中的重複。

YAML 中的多行字串有兩種風格：字面區塊純量（|），保留換行——用於 Shell 指令碼、SQL 查詢或任何換行重要的內容；以及折疊區塊純量（>），將換行折疊為空格（類似 HTML 的處理方式）——用於長段落、描述或應重新排版的文字。使用 |-（移除尾隨換行）或 |+（保留尾隨換行，包括額外的換行）來覆寫預設的尾隨換行行為。

YAML 對註解（# 註解）的支援是其在組態檔方面優於 JSON 的最大優勢。註解讓您可以記錄為何選擇某個值、連結到 Jira 問題單、標記 TODO 與說明不明顯的設定——全部不會破壞剖析器。JSON 與 JSON5 的變通方案（如 "__comment": "explanation"）是駭客手法；在 YAML 中，註解是一等公民。

YAML 合併鍵（<<）是一種特殊的映射鍵，將一個映射中的鍵合併到另一個映射中。它是 YAML 1.1 規範的一部分，雖然不在 YAML 1.2 核心中，但仍被廣泛支援。Docker Compose 大量使用合併鍵與錨點來定義服務範本。然而，合併鍵在巢狀映射中存在已知的邊界情況——請明確表示對深層合併與淺層合併的期望。

在 CI/CD 中於部署前驗證 YAML 檔案。一個在本機測試通過但在 CI 中失敗的格式錯誤 YAML 浪費開發者時間。將 YAML lint 步驟新增到您的管線中：`yamllint .` 或 `python -c "import yaml; yaml.safe_load(open('config.yaml'))"`。我們的線上驗證器現在整合了 GitHub Actions——在您的儲存庫中新增一個顯示 YAML 組態驗證狀態的徽章。

在除錯因神秘的「error converting YAML to JSON」而無法啟動的 Kubernetes Pod 時，問題幾乎總是清單中的 YAML 格式錯誤。我們的格式化器捕捉縮排錯誤、重複的鍵（YAML 中最後一個值無聲勝出——這是設定被神秘忽略的常見原因），以及放置在錯誤巢狀層級的欄位。格式化您的清單，然後使用 kubectl 重新套用。