YAML 集合類型：Map 與 List

在認識了基礎的「純量」後，接著我們要學習如何將資料組織起來。YAML 提供兩種核心的集合結構：Map (映射) 與 List (列表)。

這兩者的組合能讓你表達極其複雜的資料關係。

Map (映射/字典/物件)

Map 是由「鍵值對」組成的集合，類似於程式語言中的 Dictionary、Hash 或 Object。

基本寫法 (Block Style)

在 YAML 中，這是最常見的寫法，每個鍵佔一行，並使用縮排表示層級。

# 一個簡單的 Map
user:
  id: 101
  name: 'Alice'
  role: 'Admin'

流式寫法 (Flow Style)

如果你希望更精簡，可以使用類似 JSON 的大括號 {}。這在撰寫簡單的巢狀結構時非常方便。

# 與上方等效的流式寫法
user: { id: 101, name: 'Alice', role: 'Admin' }

List (列表/陣列/序列)

List 是一組有序的資料集合，類似於程式語言中的 Array。

基本寫法 (Block Style)

使用一個「減號 -」加上一個空格。

# 一個簡單的 List
skills:
  - 'Python'
  - 'Go'
  - 'Docker'

流式寫法 (Flow Style)

使用中括號 []，並以逗點分隔。

# 與上方等效的流式寫法
skills: ['Python', 'Go', 'Docker']

巢狀組合 (Nested Structures)

YAML 的強大之處在於你可以隨意組合 Map 與 List。

List 中包含 Map

這是處理一系列物件時最常用的格式（例如 Kubernetes 的環境變數設定）。

# 使用者列表
employees:
  - name: 'Mike'
    department: 'IT'
  - name: 'Jerry'
    department: 'Sales'

Map 中包含 List

用於表示一個鍵擁有多個值（例如標籤、分類）。

# 文章資訊
post:
  title: 'YAML 教學'
  tags:
    - Tutorial
    - Config
    - Dev

關鍵的縮排與空格規則 (Indentation Rules)

縮排是 YAML 的靈魂，錯誤的縮排會導致資料結構完全被解讀錯誤。

Map 的縮排

子項名稱的「開頭」必須比父項名稱的「開頭」更靠右。

# 正確：child 比 parent 靠右
parent:
  child: value

# 錯誤：沒有縮排，child 會被視為與 parent 同級
parent:
child: value

List 的縮排（重點！）

清單項目的減號 - 相對於父鍵，可以選擇「縮排」或「不縮排」（對齊父鍵），這兩種寫法在 YAML 中都是合法的，但同一檔案內應保持一致。

# 寫法 A：減號縮排（推薦，階層感較明顯）
fruits:
  - Apple
  - Banana

# 寫法 B：減號對齊父鍵
fruits:
- Apple
- Banana

3. List 中包含 Map 的「緊湊式」縮排

這是最常見的「物件陣列」寫法。當 List 的項目是一個 Map 時，通常會將 Map 的第一個鍵緊接在減號後面。

# 專業的緊湊寫法
users:
  - id: 1
    name: 'Alice'
  - id: 2
    name: 'Bob'

# 注意：第二行開始的 'name' 必須對齊第一行的 'id'

常見錯誤清單

❌ 冒號與減號後忘記空格

冒號 : 與減號 - 之後必須接一個空格，否則 YAML 解析器會將其視為字串的一部分。

invalid:key       # 冒號後沒空格（錯誤）
-item             # 減號後沒空格（錯誤）

❌ 使用 Tab 進行縮排

YAML 規格書嚴格禁止使用 Tab 鍵進行排版。如果你在編輯器中按了 Tab，請確保你的編輯器設定會自動將其轉為空格。

❌ 同一階層未對齊

屬於同一個集合的項目，左側的起始位置必須完全一致。

# 錯誤：Banana 沒有對齊 Apple
list:
  - Apple
    - Banana

學會了如何組織資料後，你已經能處理 80% 的 YAML 場景了。