TL;DR — 30 秒掌握 YAML
- YAML 是以縮排（空白）表示資料階層結構的、人類易讀的資料序列化格式。
- 涵蓋的字串、數值、布林值、null、陣列（清單）、物件（對應）等資料模型與 JSON 相同。
- 省去大括號、逗號，廣泛用於設定檔的撰寫。
- Kubernetes manifest、GitHub Actions workflow、Docker Compose、Ansible 等主流 DevOps 工具皆以 YAML 為標準格式。
- 支援 JSON 沒有的註解（
#）、多行字串（|、>）以及錨點（&）與別名（*）的資料重用。 - 想在瀏覽器中檢查 YAML 語法或轉換成 JSON，可以使用 YAML to JSON 轉換器，出錯時會標示行號。
YAML 是什麼？
YAML 是專為人類易於閱讀與書寫而設計的資料序列化（Data Serialization）格式，主要用於應用程式設定檔或基礎設施程式碼（IaC）的定義。
YAML 這個名稱原本是 "Yet Another Markup Language"（又一種標記語言）的縮寫，但為了強調它與 HTML/XML 不同、專注於純資料表達，正式名稱被改為遞迴縮寫 "YAML Ain't Markup Language"（YAML 不是標記語言）。
YAML 由 Clark Evans 等人於 2001 年提出，目前廣泛使用的 YAML 1.2 規範將其定義為 JSON 的上位集合（Superset）。也就是說，語法上合法的 JSON 文件也可以被解析為合法的 YAML 文件。
最大特色是以縮排（Indentation）代替大括號來表示階層結構。以相同資料分別用 YAML 和 JSON 寫出來比較，就能直覺理解差異：
name: Alice
age: 30
isStudent: false
{
"name": "Alice",
"age": 30,
"isStudent": false
}
YAML 省去了大括號、key 的引號、以及行末逗號，僅以縮排和換行來呈現。在需要人手編輯的設定檔中，這種可讀性是一大優勢。若要深入了解兩種格式的差異，包括型別、註解、錨點與不同解析器的行為，可參考 YAML JSON 比較。
YAML 基本語法與撰寫規則
鍵值對（Key-Value）
以冒號加空白（: ）分隔 key 與 value。冒號後方必須至少有一個空白（space）。大部分情況下引號可以省略。
name: 王小明
age: 30
city: 台北
引號必須使用的情況：可能被自動解析為其他型別的 value（version: "1.0"、country: "NO"），或包含語法特殊字符的字串（message: "Error: file not found"）。
縮排與階層結構（Nesting）
YAML 使用空白的縮排來表達父子關係。
- 只允許空白（Space）：Tab 字符在語法上被嚴格禁止。
- 保持一致的寬度：通常使用 2 個空白。
user:
name: 王小明
address:
city: 台北市
district: 信義區
陣列（清單）
使用短線加空白（- ）來寫入清單項目。也支援一行式（Flow）語法：
fruits:
- 蘋果
- 香蕉
- 柳橙
fruits: [蘋果, 香蕉, 柳橙]
註解（Comment）
# 從該位置到行末皆被視為註解。JSON 不正式支援註解，因此能在設定檔中留下說明與背景，是 YAML 最大的優勢之一。若想讓 JSON 也能附上類似說明，可參考 JSON 註解方式 介紹的 4 種替代方法。
# 資料庫連線設定
database:
host: localhost # 上線環境需改用網域名稱
port: 5432
YAML 沒有 /* ... */ 這樣的區塊註解語法，跨多行寫註解時每一行都必須各自加上 #。在 VS Code、IntelliJ、Vim 等編輯器中，選取範圍後按下註解切換快捷鍵（Cmd + / 或 Ctrl + /），就能一次對多行加上或移除 #。
以註解暫時停用設定
# 可以用在行中間或行首，因此在不刪除設定的情況下暫時停用時非常方便。
timeout: 30
# timeout: 60 # 舊設定值（備查）
# 要能被辨識為註解，前面必須有空白或位於行首。若寫成 key: a#b，# 會被視為字串 value 的一部分。
多行字串（Multi-line Strings）
| 保留換行原樣，> 將換行合併為空白：
description: |
這是第一行。
這是第二行。
description: >
這句話為了可讀性拆成多行，
但實際會被處理成一行長字串。
資料型別與隱式型別轉換
YAML 解析器會根據 value 的形態自動推斷型別。除了 true、false 之外，YAML 1.1 規範的解析器也會將 yes、no、on、off 自動轉為布林值。null、~、或冒號後方留空都會被處理為 null。
integer_val: 100
float_val: 3.14
boolean_val: true
null_val: ~
empty_val:
錨點與別名（值重用）
YAML 支援錨點（&）、別名（*）以及合併鍵（<<）來減少設定中的重複：
default_config: &default_settings
timeout: 30
retries: 3
production:
<<: *default_settings
timeout: 60
development:
<<: *default_settings
debug: true
透過 <<: *default_settings 將共用設定帶入，僅需個別覆寫需要的 key。
YAML 常見的使用場景
Kubernetes manifest
Kubernetes 的 Pod、Deployment、Service、ConfigMap 等所有資源定義皆以 YAML 為標準。
apiVersion: apps/v1
kind: Deployment
metadata:
name: web-app
spec:
replicas: 3
selector:
matchLabels:
app: web
template:
metadata:
labels:
app: web
spec:
containers:
- name: nginx
image: nginx:1.25
ports:
- containerPort: 80
GitHub Actions workflow
定義 CI/CD 管線的 .github/workflows/*.yml 檔案全部以 YAML 撰寫。
name: CI
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm test
Docker Compose
services:
web:
image: nginx:latest
ports:
- "8080:80"
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: secret
其他工具
Ansible playbook、Spring Boot 的 application.yml、OpenAPI（Swagger）定義文件、靜態網站產生器（Jekyll、Hugo、Astro）的 Markdown Frontmatter 中使用的 YAML 金資料等。在靜態網站產生器中處理 frontmatter 時，YAML 轉 JSON 有 5 個容易踩到的陷阱，詳見 Markdown frontmatter 格式與語法。
撰寫 YAML 時常見的陷阱
使用 Tab 導致語法錯誤 — YAML 檔案中最常發生的錯誤。Tab 字符會被解析器拒絕，請在編輯器設定中啟用「按下 Tab 時插入空白」。
挪威問題（Norway Problem） — 使用 YAML 1.1 規範的解析器（例如 PyYAML）會將未加引號的 NO、no、YES、yes、ON、off 自動轉換為布林值。挪威的國家代碼 NO 被當成 false 是最具代表性的案例。要安全地當作字串處理，必須以 country: "NO" 的形式加引號。
冒號後遺漏空白 — key:value 會被當作單一字串，不會被識別為 key-value 對應。必須以 key: value 的形式撰寫。
縮排深度不一致 — 同一區塊中混用 2 格與 4 格縮排，解析器會將親子關係解讀錯誤或產生語法錯誤。
若想系統性檢查縮排、型別、錨點等各項語法的正確寫法，可參考 YAML 語法教學。
YAML 與 JSON 互轉
YAML 與 JSON 共用幾乎相同的資料模型，可以自由互轉。YAML 轉 JSON 適用於將人類易讀的設定交給程式或 API 使用；JSON 轉 YAML 適用於將 API 回應或既有 JSON 設定轉換為可讀性高的 YAML 文件或 Kubernetes manifest。YAML 轉 JSON 的具體步驟與常見陷阱，見 YAML 轉 JSON 指南；反方向的 JSON 轉 YAML 在 Kubernetes、Docker Compose、Ansible 上的實務比較，見 JSON 轉 YAML 比較。
在瀏覽器中即可輕鬆完成轉換並進行語法檢查：
- YAML to JSON 轉換器 — 貼上 YAML 文字後即時驗證並轉換為 JSON，出錯時會標示問題行號與原因。
FormatArc 的所有資料轉換作業僅在用戶的瀏覽器本地環境中執行，不會將資料傳送至伺服器，因此即便是包含機密的設定檔也能安全地進行驗證。
常見問題（FAQ）
YAML 是什麼縮寫？
"YAML Ain't Markup Language"（YAML 不是標記語言）。最初是 "Yet Another Markup Language"，但為了表明它是純資料表達格式而非文件標記，改用了這個遞迴縮寫。
YAML 是程式設計語言嗎？
不是。YAML 是沒有條件分支、迴圈、函式等邏輯控制結構的純資料序列化格式。
.yml 和 .yaml 副檔名有差異嗎？
沒有。所有 YAML 解析器對兩種副檔名的處理方式相同。官方規範建議 .yaml，但短一字的 .yml 也非常普遍。
為什麼 Kubernetes 或 GitHub Actions 用 YAML 而不是 JSON？
因為對人類而言更易於目視檢查與編輯，省去大括號與逗號後視覺負擔較輕，且能自由撰寫說明設定理由的註解。
YAML 與 JSON 的主要差異是什麼？
資料模型相同，但 YAML 使用縮排並提供註解、多行字串、錨點功能。JSON 使用大括號與逗號，語法較嚴格且解析速度快，主要用於系統間的 API 通訊。若需要完整了解 JSON 本身的語法檢查、格式化與六種資料型別，可參考 JSON 格式是什麼。
為什麼 country: NO 會被變成 false？
YAML 1.1 規範中將 NO、no、YES、yes 等定義為布林值的別名。需以 country: "NO" 加引號來明確指定為字串。
總結
- YAML 是以縮排表示階層結構的直覺、易讀資料格式。
- 支援 JSON 沒有的註解（
#）、多行文字（|、>）、錨點（&）等便利功能。 - 已成為 Kubernetes、GitHub Actions、Docker Compose 等現代 DevOps 設定的標準格式。
- 需注意禁止使用 Tab 字符、冒號後必須有空白、以及
NO等隱式布林值轉換。 - 需要撰寫或驗證 YAML 時，可用瀏覽器端的 YAML to JSON 轉換器 輕鬆安全地檢查語法錯誤。