YAML 語法教學：實用入門指南

YAML（YAML Ain't Markup Language）是一種人類可讀的資料序列化格式，廣泛用於設定檔、CI/CD 流水線和基礎設施即程式碼。如果你使用 Docker Compose、Kubernetes、GitHub Actions 或 Ansible，你已經每天都在使用 YAML。本教學涵蓋你所需的一切，讓你能自信地撰寫 YAML。

為什麼選擇 YAML？

YAML 的主要優勢是可讀性。比較同一份資料在 JSON 和 YAML 中的表現：

JSON：

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "debug": true,
    "allowed_origins": ["http://localhost:3000", "https://example.com"]
  }
}

YAML：

server:
  host: localhost
  port: 8080
  debug: true
  allowed_origins:
    - http://localhost:3000
    - https://example.com

YAML 以更少的標點符號達到相同的結構。沒有大括號、簡單情況下沒有方括號、不需要強制加引號。這使得設定檔更容易閱讀和手動編輯。

基本資料類型

純量

YAML 會自動從值推斷類型：

string: hello world          # 字串（不需要引號）
quoted: "hello world"        # 明確字串
integer: 42                  # 整數
float: 3.14                  # 浮點數
boolean: true                # 布林值（true/false、yes/no、on/off）
null_value: null             # Null（也可使用 ~ 或留空）
date: 2025-01-15             # 日期（ISO 8601）

常見陷阱：yes、no、on、off 等值會被解讀為布林值。如果你要表示字串 "yes"，請加引號："yes"。

字串與引號

字串通常不需要引號，但某些情況下需要：

plain: This is a plain string
single: 'Preserves \n as literal backslash-n'
double: "Interprets \n as newline"
colon: "value: with colon needs quotes"
hash: "value # with hash needs quotes"

多行字串

YAML 有兩種多行樣式：

字面區塊（|） — 保留換行：

description: |
  This is line one.
  This is line two.
  
  This is line four (after blank line).

折疊區塊（>） — 以空格連接行：

description: >
  This is a long paragraph
  that will be folded into
  a single line.

加上 - 可去除尾部換行（|-、>-），加上 + 則保留（|+、>+）。

集合

列表（序列）

# Block 樣式
fruits:
  - apple
  - banana
  - cherry

# Flow 樣式（行內）
fruits: [apple, banana, cherry]

映射

# Block 樣式
person:
  name: Alice
  age: 30
  city: London

# Flow 樣式
person: {name: Alice, age: 30, city: London}

巢狀結構

departments:
  - name: Engineering
    lead: Alice
    members:
      - Bob
      - Charlie
  - name: Design
    lead: Diana
    members:
      - Eve

錨點與別名

錨點（&）和別名（*）讓你能重複使用值：

defaults: &defaults
  adapter: postgres
  host: localhost
  port: 5432

development:
  database: dev_db
  <<: *defaults

production:
  database: prod_db
  <<: *defaults
  host: db.example.com  # 覆寫預設值

<< 合併鍵會合併錨點中的所有屬性。合併之後定義的屬性會覆寫錨點中的值。更多進階錨點模式請參閱我們的 YAML 錨點與別名指南。

多文件

單一 YAML 檔案可以包含多個文件，以 --- 分隔：

---
# 文件 1：Config
apiVersion: v1
kind: ConfigMap
---
# 文件 2：Service
apiVersion: v1
kind: Service

這在 Kubernetes 清單中很常見。

常見陷阱

1. 縮排錯誤

YAML 使用空格，絕不使用 Tab。不一致的縮排是最常見的錯誤：

# 錯誤——混合縮排
server:
  host: localhost
    port: 8080  # 錯誤：意外的縮排

# 正確
server:
  host: localhost
  port: 8080

使用我們的 YAML 格式化工具自動修正縮排問題。

2. 挪威問題

像 NO（挪威）這樣的國碼會被解讀為布林值 false：

# 錯誤
countries:
  - NO  # 被解讀為 false！
  - SE
  - DK

# 正確
countries:
  - "NO"
  - SE
  - DK

3. 未加引號的特殊字元

值中的冒號、井號和方括號需要加引號：

# 錯誤
message: Error: file not found
url: http://example.com  # 可能會出問題

# 正確
message: "Error: file not found"
url: "http://example.com"

4. 版本號陷阱

像 1.0 這樣的版本號會被解析為浮點數：

# 錯誤
version: 1.0  # 變成 1（浮點數）

# 正確
version: "1.0"  # 字串

驗證 YAML

部署前務必驗證你的 YAML。YAML 中的語法錯誤可能導致應用程式出現難以理解的故障。我們的 YAML 驗證器可即時檢查語法，精確標出任何錯誤的行和列。

若想更深入了解 YAML 和 JSON 之間的差異，請參閱我們的 YAML vs JSON 比較。

常見問題

YAML 縮排應該用幾個空格？

兩個空格是最常見的慣例，Kubernetes、Docker Compose、GitHub Actions 和大多數 DevOps 工具都使用它。有些專案使用四個空格。關鍵規則是在檔案內保持一致——絕不混用不同的縮排層級。

YAML 可以包含註解嗎？

可以，YAML 支援以 # 開頭的單行註解。沒有多行註解語法。註解在解析時會被去除，不會出現在載入的資料結構中。