YAML 多行字串處理

在處理設定檔時，我們有時需要儲存一段長文字（例如 SQL 語句、私鑰內容或是一段說明的 HTML）。YAML 提供了非常強大的語法來控製多行字串的換行行為。

這也是 YAML 優於 JSON 的地方之一，因為在 JSON 中你必須手動插入無數個 \n。

保留換行 (Literal Style) |

如果你希望 YAML 完整保留你在編輯器中看到的內容格式（包括換行），請使用直線符號 |。

# 使用 | 會保留每一行的換行符號
description: |
  這是一段長文字。
  第一行會換行。
  第二行也會換行。

解析後的結果：

這是一段長文字。\n第一行會換行。\n第二行也會換行。

Literal Style | 規則總結：

• 行首空格：不保留與基準縮排對齊的空格。保留超過基準縮排的額外空格。
• 行末空格：完全保留。
• 换行符號：完全保留。你在 YAML 怎麼換行，輸出的字串就怎麼換行。
• 區塊末尾空行：無論你末尾留了幾行空行，輸出時都會被縮減為恰好一個換行符號 \n。

摺疊換行 (Folded Style) >

如果你希望在 YAML 檔案中為了美觀而分行撰寫，但希望解析後它們能自動合併成一行（以空格分隔），請使用大於符號 >。

# 使用 > 會把相鄰的換行符轉成空格
intro: >
  這是在檔案中
  被分成三行的文字，
  但會合在一起。

解析後的結果：

這是在檔案中 被分成三行的文字， 但會合在一起。

Folded Style > 規則總結：

• 行首空格：不保留基準縮排。但若某行縮排比第一行深，該行會被視為「特殊區塊」，保留換行與縮排，不參與摺疊。
• 行末空格：不保留（會被換行轉換機制吃掉）。
• 换行符號：
  • 單次換行：轉換為一個空格。
  • 两次换行 (空行)：轉換為一個換行符號。
  • 多次換行（空行）： 具體來說，中間的 n 個換行符號，在解析後會變成 n-1 個換行符號 \n。
• 區塊末尾空行：無論末尾留幾行，輸出時都只會保留一個換行符號 \n。

末尾換行控制 (Block Chomping)

YAML 還允許你微調字串「末尾」的換行符號該如何處理。這透過在 | 或 > 後面加上 + 或 - 來達成。

除去 (Strip) -

刪除區塊末尾所有的換行與空行，確保字串結束後不會多出一個空白行。

# 末尾完全不留換行
content: |-
  Hello
  World

解析後的結果：

Hello\nWorld

|- 核心邏輯：

• 內部換行與空格：與 | 一樣
• 區塊末尾空行：全部刪除。輸出的字串末尾不會有任何換行符號，直接結束。

# 內部換行變空格，結尾完全乾淨
folded_strip: >-
  This is line 1
  This is line 2

解析後的結果：

This is line 1 This is line 2

>- 核心邏輯：

• 內部換行與空格：與 > 一樣
• 區塊末尾空行：全部刪除。輸出的字串末尾不會有任何換行符號，直接結束。

保留 (Keep) +

保留字串末尾所有的換行符（包括多餘的空行）。

# 末尾保留所有空行
content: |+
  Hello
  World

解析後的結果： Hello\nWorld\n\n\n

核心規則：

• 內部換行與空格：與 | 一樣。
• 結尾完整保留（Keep）：文字區塊最後方的所有空行都會被保留下來，轉換成對應數量的 \n。

>+ 這個符號較少見，它會摺疊文字，但會強行保留你在 YAML 檔中刻意留下的所有尾部空行。

# 內部換行變空格，結尾保留所有空行
folded_keep: >+
  This is line 1
  This is line 2

解析後的結果：

This is line 1 This is line 2\n\n\n

>+ 核心邏輯：

• 內部換行與空格：與 > 一樣
• 結尾完整保留（Keep）：文字區塊最後方的所有空行都會被保留下來，轉換成對應數量的 \n。

預設 (Clip)

如果不加符號，YAML 的預設行為是：將末尾的多個空行壓縮為「一個」換行符。

比較表

實務範例：私鑰 (Private Key)

這是在 DevOps 中最常見的應用場景。因為私鑰的格式非常嚴格，每一行都必須對其，所以我們必定使用 |。

ssh_key: |
  -----BEGIN RSA PRIVATE KEY-----
  MIIEpAIBAAKCAQEA75R...
  ...中間略過...
  -----END RSA PRIVATE KEY-----

掌握了多行字串的處理技巧後，你的 YAML 檔就能處理各種複雜的文字內容了！