單元 2 · 基本語法

2.1 鍵值對 · Key-Value Pairs

YAML 最基本的單位是 鍵: 值。冒號後要加一個空格——這條鐵則沒有例外，也是新手第一個踩的坑。

name: YAML 教學
author: OpenCode
units: 8

{"name": "YAML 教學",
 "author": "OpenCode",
 "units": 8}

2.2 縮排 · Indentation（最重要）

巢狀層級靠縮排表達，這是 YAML 之所以好讀、也之所以難 debug 的原因。規則有三：同層縮排一致、只能用空格、禁用 Tab、慣用兩個空格。

app:
  database:
    host: db.example.com
  cache:
    ttl: 60

{"app": {
    "database": {"host": "db.example.com"},
    "cache":    {"ttl": 60}}}

2.3 註解 · Comments

用 # 開頭到行尾皆為註解，可佔一整行，也可放在行尾。註解是 YAML 打敗 JSON 的殺手級功能——設定檔需要解釋「為什麼」。

# 這是註解
name: YAML 教學   # 行尾註解也行
# 注意：值開頭是 # 就不是註解，是字串，要加引號（單元 3）

2.4 空值 · Null

空值可以寫 null、~，或直接留空（冒號後不寫值）。三者等價。

a: null
b: ~
c:
d: null   # 三者等價

{"a": null, "b": null,
 "c": null, "d": null}

2.5 文件分隔 · Document Separator

一個檔案可含多份文件，用 --- 分隔；... 表示文件結束。多數設定檔只用一份，但 frontmatter 就是利用檔首的 --- 區塊（Jekyll / Hugo / Obsidian），單元 7 會看到實例。

---
first: 文件一
---
second: 文件二
...

多份文件在 Python 用 yaml.safe_load_all、在 yq 用 yq 'eval-all' 讀取。

2.6 Worked Example：從零寫一個設定檔

# 應用程式設定
title: 我的服務
replicas: 3
features:
  auth: true
  cache: true
tags: [web, api]
notes: null

練習：幫你手上的專案寫一個 config.yml，包含標題、三個以上鍵值、一層巢狀與一行註解，然後用 yaml.safe_load 讀回來檢查。

延伸閱讀

• 上一篇：單元 1 · YAML 是什麼。
• 下一篇：單元 3 · 字串與引號。
• 術語表：複習全站。

進階真實情境 Worked Example：Ansible Inventory

Ansible 的 inventory 檔大量使用 YAML 基本語法——鍵值對、巢狀對映、多文件分隔、空值。以下是一份真實場景：

---
# Ansible inventory — 生產環境
all:
  vars:
    ansible_user: deploy
    ansible_port: 22
  children:
    webservers:
      hosts:
        web1.example.com:
        web2.example.com:
    databases:
      hosts:
        db1.example.com:
          ansible_port: 5432
...

為什麼這樣設計而非替代方案：Ansible inventories 故意讓 host 名稱作為「無值的鍵」（等同 null），因為 host 本身就是標識——不需要值。用 --- / ... 包圍是 YAML 慣例，讓解析器明確知道這是一份完整文件。

深入原理擴充

Implicit vs Explicit Key

YAML 對映的鍵有兩種寫法：implicit key（plain string，不需要引號）與 explicit key（加引號）。在 block context 中，implicit key 只能是「單行的純量」——一旦鍵名含有 :、#、{、}、[、]、, 等字元，就必須加引號變成 explicit key。例如 "key: with colon": value 在 YAML 1.2 是合法的。

大家以為是這樣但其實不是……

診斷式疑難排解表

進階挑戰題

1. 多文件操作：在同一個 .yml 檔中用 --- 分隔三份文件，分別是 dict、list、scalar。用 Python yaml.safe_load_all() 讀取並印出每份文件的 type()。
2. 隱性 bug 偵測：故意在 YAML 中放一個「冒號後沒空格」的值，再放一個「正確寫法」的值。用 yaml.safe_load 讀取，比較兩者的差異。如果冒號後沒空格的值「看起來」是對的，怎麼發現它是錯的？
3. 設計挑戰：設計一份「零陷阱」的 YAML 設定檔——所有值都用最安全的寫法（明確型別、必要時加引號），然後與一份「自然寫法」的版本對比，討論可讀性與安全性的權衡。

① 專案級端到端 Worked Example：Ansible 多主機佈建專案

基本語法（鍵值對、巢狀、多文件、空值）組合起來就是真實的部署專案。以下是一個用 Ansible 佈建三台主機的完整專案：

產出檔案樹

provisioner/
├── inventory/
│   └── production.yml      # 主機清單（多文件 + 巢狀 + 空值）
├── group_vars/
│   └── all.yml             # 全域變數（鍵值對）
├── playbooks/
│   ├── deploy.yml          # 主 playbook
│   └── healthcheck.yml     # 健康檢查
└── ansible.cfg             # INI 格式，非 YAML——工具混用是常態

關鍵檔案內容

---
all:
  vars:
    ansible_user: deploy
    ansible_port: 22
  children:
    webservers:
      hosts:
        web1.example.com:
        web2.example.com:
    databases:
      hosts:
        db1.example.com:
          ansible_port: 5432
...

# 所有主機共用的變數
app_version: "1.4.2"     # 加引號防型別誤判
app_replicas: 3
log_level: info
features:
  - metrics
  - tracing
maintenance_mode: false

---
- name: 部署應用
  hosts: webservers
  tasks:
    - name: 確認變數已注入
      debug:
        msg: "版本 {{ app_version }}"
    - name: 部署容器
      community.docker.docker_container:
        name: app
        image: "myapp:{{ app_version }}"
        restart_policy: unless-stopped

$ ansible-playbook -i inventory/production.yml playbooks/deploy.yml --syntax-check
playbook: playbooks/deploy.yml

$ ansible-inventory -i inventory/production.yml --list | python3 -m json.tool | head -20
{
    "_meta": {
        "hostvars": {
            "db1.example.com": {"ansible_port": 5432}
        }
    },
    "all": {
        "children": ["databases", "webservers"]
    }
}

② 效能/品質/安全深度

品質：縮排是最大的自動化敵人的檢查面

在佈建自動化中，縮排錯誤可能不是「報錯」而是「部署到錯誤的機器群」：同層縮排差一格，任務就換了 hosts。品質防線：

• yamllint：抓縮排、行長、重複鍵——接進 pre-commit 與 CI。
• ansible-lint：抓 playbook 結構錯誤與反模式（behaviour 層面）。
• --syntax-check：僅解析，不連線，秒級回饋。

安全：inventory 是密碼存放的雷區

效能：inventory 檔案規模

幾千台主機的 inventory 解析與 hostvars 合併是有成本的——Ansible 會對每個 host 執行變數合併。實務上拆成 group_vars / host_vars 目錄，讓 Ansible 只載入需要的部分，而不是一支超長單檔。

③ 站際比較對照表

④ 互動式檢核清單

• 能憑空寫出一份含鍵值對、兩層巢狀、註解、空值的 config.yml，並用 safe_load 驗證。
• 能解釋「冒號後沒空格」的報錯特徵，並用 cat -A / 編輯器診斷 Tab 混用。
• 能讀懂 Ansible inventory 的「無值鍵 = host 名稱」慣例，並正確覆寫單台主機的變數。
• 能為自己的部署專案建立 ansible-playbook --syntax-check + yamllint 的 CI 門檻。
• 能判斷哪些值該放 group_vars、哪些該放 host_vars，並說明理由。
• 知道敏感值該用 ansible-vault 加密，並能說明加密流程。