單元 3 · 字串與引號

3.1 三種寫字串的方式

YAML 字串有三種寫法，沒有引號是預設（plain），遇到特殊字元才需要引號：

3.2 何時必須加引號

值的開頭或內容含這些字元時，最好加引號——否則會被誤解成別的東西：

a: "字串: 內含冒號"      # 冒號後跟空格
b: "#不是註解"          # 值開頭是 #
c: "- 開頭像清單"        # 值開頭是 - 
d: "含 前導 空 格"       # 需要保留前導空格
e: "yes,真的"           # 避免被當布林（見單元 5）

3.3 單引號 vs 雙引號

single: '直接顯示 
 不是換行'
double: "這會
換行"
single_q: 'It''s YAML'   # 兩個單引號 = 一個引號

3.4 多行字串：保留換行 · Block Scalar |

用 | 表示「換行全都保留」——適合程式碼、shell 指令、日誌。

script: |
  #!/bin/bash
  echo "hello"
  exit 0

#!/bin/bash
echo "hello"
exit 0

3.5 多行字串：摺疊換行 · Folded Scalar >

用 > 表示「軟換行摺疊成空格」——適合長段落、README 描述。

description: >
  這是一段很長的文字，
  在原始檔分成兩行，
  讀出來會變成一行。

這是一段很長的文字， 在原始檔分成兩行， 讀出來會變成一行。

3.6 修剪後綴 · Chomping

| / > 後面可加一個字元控制結尾換行：

keep: |          # 保留所有結尾換行（預設也是保留單一結尾換行）
strip: |-         # 去除所有結尾換行（最後一行沒 
）
clip: |+         # 保留多個結尾換行

實務上 |- 最常用——例如把一段多行字串併進單一環境變數時，不需要結尾換行。

3.7 Worked Example：把一段描述塞進變數

banner: |-
  Welcome to YAML course.
  Learn by doing.
script: |
  npm ci
  npm test

練習：寫一段 | 多行字串存 shell script，再用 |- 寫一段單行摘要，分別用 yq 或 Python 讀出，觀察結尾 \n 差異。

延伸閱讀

• 上一篇：單元 2 · 基本語法。
• 下一篇：單元 4 · 序列與巢狀。
• 術語表：複習全站。

進階真實情境 Worked Example：API OpenAPI 規格片段

OpenAPI（Swagger）規格檔大量使用多行字串描述 API 文件。以下是一段真實場景：

paths:
  /users:
    get:
      summary: 取得使用者列表
      description: >
        回傳所有已註冊的使用者。
        支援分頁參數 page 與 limit。
        預設每頁回傳 20 筆。
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          description: '# 頁碼從 1 開始'

為什麼這樣設計而非替代方案：description 用 > 而非 | 是因為 API 文件是一段連續文字，不需要保留換行；如果用 | 每行會帶 \n，在 Swagger UI 中渲染會有額外空行。用單引號包住 '# 頁碼…' 是因為值開頭是 #，不加引號會被當註解。

深入原理擴充

Folded Scalar 的換行規則

> 摺疊_scalar 預設（clip）行為：空行會被保留為 \n\n，而連續行之間的換行會被替換成空格。但有個例外：如果下一行的縮排與首行相同，且中間沒有空行，那換行會被摺疊成空格；如果中間有空行（blank line），則那個空行會被保留。這意味著 > 的結果不是「全部連成一行」，而是「段落內換行摺疊、段落間保留空行」。

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

診斷式疑難排解表

進階挑戰題

1. 三種引號實驗：用 plain、單引號、雙引號分別定義同一個值 Hello "World"，用 yaml.safe_load 讀出後比對三者結果。哪種寫法最簡潔？哪種最明確？
2. Chomping 組合：同一段多行文字，分別用 |、|-、|+ 定義，用 Python 印出 repr() 比較三者的結尾換行差異。
3. 真實 bug 重現：在 YAML 中寫 key: This is a # comment（值中間含 #），解析後值是什麼？再寫 key: "#hashtag"，解析後又是什麼？解釋差異的原因。

① 專案級端到端 Worked Example：GitHub Actions 多步驟部署 workflow

字串技巧（plain/引號/多行 block scalar）在 CI workflow 中最密集——run: 步驟幾乎都是多行 shell 腳本。以下是完整的部署專案：

產出檔案樹

deploy-app/
├── .github/
│   └── workflows/
│       └── deploy.yml      # 主 workflow（多行字串大本營）
├── scripts/
│   ├── build.sh            # 被 YAML 多行字串呼叫的腳本
│   └── notify.sh           # 部署後通知
└── README.md

關鍵檔案內容

name: Deploy
on:
  workflow_dispatch: {}
  push: {tags: ["v*"]}

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      VERSION: "${{ github.ref_name }}"
      REGION: ap-northeast-1
    steps:
      - uses: actions/checkout@v4
      - name: 建立並推送映像
        run: |
          docker build -t myapp:${VERSION} .
          docker push registry.example.com/myapp:${VERSION}
      - name: 部署到 K8s
        run: |
          kubectl set image deployment/app app=myapp:${VERSION}
          kubectl rollout status deployment/app --timeout=120s
      - name: 通知
        run: bash scripts/notify.sh "${{ github.ref_name }}" "${{ secrets.WEBHOOK }}"

$ actionlint .github/workflows/deploy.yml && echo OK
OK

$ yamllint -d relaxed .github/workflows/deploy.yml
(無輸出 = 通過)

$ act -n                    # 本地乾跑（dry-run）解析 workflow
[Deploy/deploy] 🚀  Start image=...  platform=...
[Deploy/deploy] ✅  Success

端到端流程：打 tag v1.2.3 → workflow 觸發 → 多行 run 建映像 → 部署 K8s → 通知。每個 | 區塊都是一段完整的 shell script，換行與縮排的正確性是部署成敗的關鍵。

② 效能/品質/安全深度

品質：字串是最常被低估的 bug 來源

字串在 YAML 中的問題不是「打錯字」而是隱形的語意差異：on 變布林、010 變八進位、"1.0" 與 1.0 行為不同。品質策略：

• 「長得像別種型別的值」一律加引號（版本、電話、ID、時間）。
• 多行內容（腳本、描述）一律用 | / >，不要用 \n 硬拼。
• 在 CI 用 actionlint / yamllint 攔截常見字串語法錯誤。

安全：多行字串 = shell 注入面

效能：多行字串對解析的影響

| / > block scalar 在大檔案中比一行行引號字串解析更快、佔用更少——因為解析器只需處理一次「區塊頭」，不必逐行做引號掃描。實務上大量腳本內容的 workflow，用 block scalar 也能讓檔案瘦身 30% 以上。

③ 站際比較對照表

④ 互動式檢核清單

• 能判斷任意一個值該用 plain、單引號還是雙引號，並說明判斷依據。
• 能寫出含 | / |- / |+ / > 的 YAML，並預測每種的結尾換行行為。
• 能修好「值開頭是 # 被當註解」「值含 : 被誤判」的實際報錯。
• 能寫出一個含多行 shell 的 workflow run: 步驟，並用 actionlint 驗證。
• 能在 shell 中正確使用 "$VAR" 包住來自 YAML 的變數，避免注入。
• 能解釋「單引號比雙引號更安全」這個說法的適用場景（含反斜線的值）。