YAML 指令完整指南：從零開始掌握最人性化的資料格式

你是否曾經打開一個設定檔，卻被密密麻麻的括號和引號搞得眼花撩亂？如果你覺得 JSON 或 XML 難以閱讀，那麼你一定會愛上 YAML。這種被稱為「最人性化」的資料格式，正以其簡潔清晰的特性，席捲軟體開發與自動化運維的世界。這篇文章將帶你從基礎語法到實務應用，徹底搞懂 YAML 指令。

什麼是 YAML？為什麼它比其他格式更受歡迎？

YAML（發音同 "Camel" 的韻，/ˈjæməl/）是一個遞迴縮寫，最初代表 "Yet Another Markup Language"（另一種標記語言），但後來為了強調其以數據為中心的特性，更名為 "YAML Ain't Markup Language"（YAML 不是標記語言）。

這看似繞口令的名稱，其實點出了它的核心價值：它不關注文字的樣式（如 HTML），而是專注於資料的結構與傳輸。

與 JSON 或 XML 等傳統格式相比，YAML 最大的特色在於「極致的可讀性」。它移除了大量繁瑣的符號（如大括號 {}、中括號 [] 和引號 ""），改用縮排（Indentation）來表示層級關係。這使得 YAML 文件看起來就像是一份條理分明的筆記或大綱，即便是非技術背景的人員也能輕鬆讀懂。

為什麼我們要學 YAML？

清晰簡潔：代碼量通常比 XML 少一半以上，比 JSON 更直觀。
廣泛支援：幾乎所有的主流程式語言（Python, Java, Go, Node.js）都支援 YAML。
配置檔首選：它是 Kubernetes、Ansible、Docker Compose 等基礎設施工具的標準格式。

重點小結：
YAML 是一種專注於資料內容而非格式的語言。
它的核心優勢在於「人類可讀性高」，去除了不必要的符號干擾。
它是目前 DevOps 與雲端技術中最主流的設定檔格式。

YAML 基礎語法：你需要知道的核心規則

要撰寫正確的 YAML 指令，其實只需要掌握幾個核心原則。雖然它的入門門檻低，但 YAML 對於「格式」的要求非常嚴格，一個空白鍵的差異都可能導致讀取失敗。

1. 縮排原則（Indentation）

這是 YAML 的靈魂。YAML 使用空白鍵的縮排來表示資料的層級結構（巢狀關係）。

嚴禁使用 Tab 鍵：這是新手最常犯的錯誤。YAML 不允許使用 Tab 鍵進行縮排，必須使用空白鍵（Space）。
對齊即同級：左側對齊在同一垂直線上的元素，被視為同一層級。
建議縮排數：雖然規範未強制，但慣例上通常使用 2 個空白鍵或 4 個空白鍵作為一層縮排。

2. 鍵值對（Key-Value Pair）

這是最基本的資料單元，格式為 Key: Value。

冒號後必須有空格：在冒號 : 之後，必須保留至少一個空白鍵，才能接數值。這是 YAML 語法檢查中最常見的報錯原因。

正確範例：

YAML

name: Gemini role: AI Assistant version: 1.5

錯誤範例（缺少空格）：

YAML

name:Gemini # 錯誤！解析器會無法識別

3. 註解（Comments）

YAML 支援單行註解，使用井字號 # 開頭。任何在 # 之後的文字都會被解析器忽略，這對於編寫複雜的設定檔（Configuration Files）非常有幫助，可以讓團隊成員理解該指令的用途。

語法要點清單：
只能用空白鍵縮排，禁用 Tab。
Key: Value 的冒號後方必留空格。
使用 # 撰寫註解，保持文件清晰。
大小寫敏感（Case Sensitive），Name 與 name 是不同的鍵。

資料結構解析：清單與字典的應用

YAML 指令的強大之處，在於它能用非常精簡的方式表達複雜的資料結構。主要分為兩大類：字典（Dictionary/Map） 與 清單（List/Sequence）。

1. 字典（Mappings）

這就是前面提到的「鍵值對」集合。當我們需要描述一個物件的多個屬性時，會使用這種結構。

範例：描述一位員工

YAML

employee: name: 王小明 department: 行銷部 skills: primary: SEO secondary: Content Writing

在這個例子中，skills 下方縮排的內容屬於 skills 的子層級，結構一目了然。

2. 清單（Lists）

當你需要列出一系列平行的項目時，使用連字號 -（減號）加上一個空格來表示。

範例：待辦事項清單

YAML

todo_list: - 撰寫部落格文章 - 檢查 SEO 關鍵字 - 發布至社群媒體

這在程式中會被轉換為陣列（Array）：["撰寫部落格文章", "檢查 SEO 關鍵字", "發布至社群媒體"]。

3. 混合使用（巢狀結構）

在實際應用中，我們通常會混合使用字典與清單。這是 YAML 最強大的地方，它能清晰地描述複雜的系統架構。

實務案例：一個簡單的伺服器配置

YAML

server: host: 192.168.1.10 ports: - 80 - 443 - 8080 users: - name: admin access: full - name: guest access: read-only

請注意觀察 users 區塊：這是一個「包含字典的清單」。每個 - 開頭代表一個使用者物件，而該物件內又包含了 name 和 access 兩個屬性。

結構重點：
字典用來描述「屬性」（是什麼）。
清單用來描述「集合」（有哪些）。
連字號 - 後面同樣需要加一個空格。

進階技巧與實務案例：讓你的 YAML 更專業

掌握了基礎後，讓我們來看看在實際工作中，如何運用進階的 YAML 指令來提升效率。

1. 處理長字串（多行文字）

在撰寫文章摘要或設定檔的描述時，文字可能會很長。YAML 提供了兩個實用的符號：

| (Literal Style)：保留換行符號。所見即所得，適合程式碼片段。
> (Folded Style)：將換行轉換為空白。適合長段落文字，讓閱讀更流暢。

範例：

YAML

description_literal: | 這是一段保留換行的文字。 description_folded: > 這是一段雖然在 YAML 中換行了但讀取時會變成同一行的文字。

2. 引用與重複使用（Anchors & Aliases）

如果你的設定檔中有大量重複的內容（例如多個服務使用相同的資料庫設定），可以使用錨點（Anchor, &）與別名（Alias, *）來避免重複輸入，這符合程式設計中的 DRY (Don't Repeat Yourself) 原則。

範例：共用設定

YAML

# 定義基本設定 (&base) default_settings: &base adapter: postgres host: localhost development: database: dev_db <<: *base # 引入 base 的所有設定 production: database: prod_db <<: *base # 再次引入，無需重寫

實務應用案例：GitHub Actions 流程檔

這是目前開發者最常接觸 YAML 的場景之一。以下是一個自動化測試的腳本範例：

YAML

name: 自動化測試流程 on: [push] # 當有程式碼推送到儲存庫時觸發 jobs: build-and-test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: 設定 Python 環境 uses: actions/setup-python@v2 with: python-version: '3.8' - name: 安裝依賴套件 run: | pip install -r requirements.txt - name: 執行測試 run: pytest

這段 YAML 指令清晰地告訴系統：當有人 Push 程式碼時，請開啟一台 Ubuntu 機器，安裝 Python 3.8，並依序執行安裝與測試指令。

常見錯誤與除錯指南

即便 YAML 易讀，新手在撰寫時仍容易踩到地雷。以下是幾個最常見的問題與解決方案：

縮排混亂：
- 症狀：解析錯誤 (ScannerError)。
- 解法：開啟編輯器的「顯示隱藏字元」功能，確保沒有混用 Tab 和 Space。建議使用 VS Code 等現代編輯器，並安裝 YAML 插件，它會自動幫你修正格式。
特殊符號未跳脫：
- 症狀：內容顯示不正確。
- 解法：如果你要在字串中使用冒號 :、大括號 {} 或井字號 # 等特殊字元，建議將整個字串用單引號 ' 或雙引號 " 包起來。
- 例如：message: "Error: Something went wrong #500"
布林值陷阱：
- 在早期的 YAML 版本中，yes 和 on 會被解析為 True，但在 YAML 1.2 版本中已逐步修正。為了保險起見，建議直接使用 true 和 false（小寫）。

結論

YAML 已經成為現代科技堆疊中不可或缺的一部分。它成功地在「機器解析」與「人類閱讀」之間取得了完美的平衡。透過掌握 縮排規則、鍵值對格式 以及 清單結構，你已經具備了撰寫 90% 以上 YAML 設定檔的能力。

隨著雲端原生（Cloud Native）技術的發展，YAML 指令的應用只會越來越廣泛。無論你是想要優化工作流程的行銷人，還是剛踏入程式領域的初學者，能看懂並修改 YAML 檔案，都將大幅提升你的數位生產力。

現在，不妨打開你的文字編輯器，試著寫一份屬於你的 YAML 自我介紹吧！

常見問答（FAQ）

Q1：YAML 和 JSON 有什麼主要差別？

YAML 是 JSON 的超集（Superset），意味著任何合法的 JSON 檔案在 YAML 解析器中也是有效的。主要的差別在於 YAML 使用縮排而非括號，更適合人類閱讀與編寫設定檔；而 JSON 則更適合作為 API 資料傳輸的格式。

Q2：YAML 檔案的副檔名應該是什麼？

最常見的副檔名是 .yaml，但也常看到縮寫為 .yml。兩者在功能上完全沒有區別，可以通用，但建議在同一個專案中統一使用一種以保持一致性。

Q3：可以用 Word 來編輯 YAML 檔案嗎？強烈不建議。

Word 等文書處理軟體會加入隱藏的排版格式與智慧引號（Smart Quotes），這會導致 YAML 解析失敗。請務必使用純文字編輯器，如 Notepad++、VS Code 或 Sublime Text。

Q4：為什麼我的 YAML 檔案一直報錯 "Mapping values are not allowed here"？

這通常是因為你在 Key: Value 的冒號後面忘記加空格，或者是縮排層級不一致所導致的。請仔細檢查報錯行數附近的縮排與空格。

Q5：YAML 支援變數嗎？

標準的 YAML 語法本身不支援像程式語言那樣的「變數運算」。但在許多工具（如 Ansible 或 Helm）中，它們使用模板語言（如 Jinja2）包裹 YAML，從而實現了變數替換的功能。但這屬於工具層面的功能，而非 YAML 原生語法。

希望這篇指南能幫助你克服對程式碼格式的恐懼！如果你想更深入了解如何將 YAML 應用在自動化工作流中，歡迎訂閱我們的電子報，獲取最新的 DevOps 入門懶人包！

覺得這篇文章有幫助嗎？ 歡迎在下方留言分享你第一次使用 YAML 遇到的趣事或困難，我們會在下篇文章中為大家解答！