YAML

你會在什麼時候遇到它

當你碰到部署與自動化工具（Docker Compose、GitHub Actions、各種伺服器的設定），設定檔就從 JSON 換成 YAML（附檔名 .yml 或 .yaml）。它出錯的方式對新手最不友好：縮排多一個空格、混進一個 Tab，錯誤訊息指到的行號卻離真正的錯處很遠。先認識「YAML 在乎什麼」，比在實務裡反覆試錯快得多。

最小範例

# 一份正確的小設定：每一層縮排兩個空格，絕不用 Tab
model: demo
options:
  temperature: 0.7
  stream: true
tools:
  - search
  - calculator

三個決定生死的細節：冒號後面要一個空格；同一層的縮排必須是完全相同的空格數；列表項以「- 」（連字號加空格）開頭。幾乎所有 YAML 錯誤都是這三條的變體。

最常搞錯的地方

• 用 Tab 縮排。YAML 規範直接禁止用 Tab 做縮排；而且不同編輯器顯示的縮排寬度不同，看起來對齊的檔案，在解析器眼裡可能整個歪掉。
• yes、no、on、off 這些詞不加引號。很多 YAML 解析器會把它們變成布林值 true／false —— 經典事故是國家代碼 NO 被解析成 false。數字 1.10 也會變成 1.1。要當文字用就加引號。