單元 6 · 錨點與別名

6.1 原理：為什麼需要重用

寫設定檔時，常常有「好幾個地方用同一組值」——例如多個服務共用相同的 restart 策略、logging 設定或環境變數。YAML 用錨點（anchor）與別名（alias）讓你定義一次、重複引用，改一處全部生效。

6.2 錨點與別名 · Anchor & Alias

&名稱 定義錨點，*名稱 引用它——引用時完整複製一份該節點。

defaults: &def
  timeout: 30
  retries: 3
api:
  *def
batch:
  *def

defaults: {timeout: 30, retries: 3}
api:      {timeout: 30, retries: 3}
batch:    {timeout: 30, retries: 3}

6.3 別名之後的覆寫

別名 *def 複製整棵節點，無法在複製的同時加欄位——想加欄位就得用合併鍵。先看「不能覆寫」的版本：

api: *def          # 就是 defaults 的副本，不能再加別的鍵
web: *def
  port: 8080   # ❌ 語法錯誤——別名節點之後不能再有內容

6.4 合併鍵 · Merge Keys <<

<< 把別名指向的對映「展開合併」進來，並可覆寫欄位——這是最實用的用法。

base: &base
  image: node:20
  ports: [8080]

web:
  <<: *base
  ports: [3000]   # 覆寫

base: {image: "node:20", ports: [8080]}

web:  {image: "node:20",   # 繼承
        ports: [3000]}     # 被覆寫

6.5 序列也能用別名

錨點不只能存對映，任何節點都能錨定——純量、序列都行。

common_args: &args [--no-cache, --progress=plain]
build_a: *args
build_b: *args

6.6 實例：Docker Compose 共用環境

經典場景——多個服務共用同一組設定。用 x- 前綴定義「延伸節點」（不是服務）當錨點來源：

x-common: &common
  restart: unless-stopped
  logging:
    driver: json-file

services:
  app:
    <<: *common
    image: myapp
  worker:
    <<: *common
    image: myworker

6.7 重用取捨與 Worked Example

錨點不是唯一選項——多數情況下「重複寫幾次」反而更直觀、更好 debug：

• 純重複：設定不常變，重複 2–3 次可接受。
• 環境變數：把共用值抽成 ${{ var }} / $VAR，執行期注入。
• 生成器：用模板/程式產生 YAML，共用邏輯留在程式裡。

defaults: &def
  retries: 5
  timeout: 60

alpha:
  <<: *def
  retries: 10     # 覆寫

beta:
  <<: *def

延伸閱讀

• 上一篇：單元 5 · 資料型別。
• 下一篇：單元 7 · YAML 生態系。
• 術語表：複習全站。

進階真實情境 Worked Example：多環境 Kubernetes 部署共用基底

企業級 K8s 設定檔常用錨點與合併鍵來定義「基底設定 + 環境覆寫」模式：

# 基底設定
x-base: &base
  image: myapp
  env:
    - name: LOG_FORMAT
      value: json
  resources:
    requests: {cpu: "100m", memory: "128Mi"}

services:
  staging:
    <<: *base
    replicas: 1
    env:                         # 完整覆寫 env
      - name: LOG_FORMAT
        value: text
      - name: DEBUG
        value: "true"
  production:
    <<: *base
    replicas: 5
    resources:
      requests: {cpu: "500m", memory: "512Mi"}

staging:
  image: "myapp"
  env: [{name:"LOG_FORMAT",
         value:"text"},
        {name:"DEBUG", value:"true"}]
  replicas: 1
  resources:
    requests: {cpu:"100m",
               memory:"128Mi"}

production:
  image: "myapp"
  env: [{name:"LOG_FORMAT",
         value:"json"}]
  replicas: 5
  resources:
    requests: {cpu:"500m",
               memory:"512Mi"}

為什麼這樣設計而非替代方案：覆寫整個 env 序列（而非逐條 append）是因為 staging 與 production 的環境變數完全不同——合併鍵是「整欄位覆寫」而非「深度合併」，這避免了「不知道 base 有哪些 env 然後意外多出一條」的隱性 bug。如果需要深度合併，通常改用程式（Helm template / Kustomize）而非 YAML 錨點。

深入原理擴充

Merge Key 的解析順序

當 << 合併鍵與其他鍵並列時，YAML 的解析順序是「先展開合併，再處理同層覆寫」。這意味著：

1. 解析器先讀取 << 指向的錨點，將其所有鍵展開到當前對映
2. 然後讀取同層的其他鍵，覆蓋展開後的同名鍵
3. 如果 << 指向的是序列（多個錨點），左邊的先展開，右邊的後展開（後展開的覆蓋先展開的）

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

診斷式疑難排解表

進階挑戰題

1. 深度合併陷阱：設計一份 base config 含三層巢狀（server: {http: {port: 80}, https: {port: 443}}），然後用 << 覆寫只改 http.port——結果 https 鍵還在嗎？用實際解析驗證，再討論如何避免。
2. 錨點 vs 環境變數：同一個共用設定，比較三種方案：(a) YAML 錨點 <<、(b) Docker Compose x- 延伸節點、(c) 環境變數 ${VAR}。列舉各自優缺點。
3. Billion Laughs 攻擊實作：用 YAML 錨點巢狀展開設計一個「10 層展開」的 YAML，計算展開後的記憶體佔用量。再用 safe_load 的限制機制防禦它。

① 專案級端到端 Worked Example：Helm chart 多環境部署專案

Helm 是「錨點 + 模板」的完美教材：values.yaml 用錨點定義共用基底，模板用 Go template 展開，環境覆寫用 values-*.yaml 分層。錨點讓「改一處，全部生效」變成可維護的工程實務：

產出檔案樹

myapp-chart/
├── Chart.yaml              # chart 中繼資料
├── values.yaml             # 預設值（錨點來源）
├── values-dev.yaml         # 環境覆寫
├── values-prod.yaml        # 環境覆寫（型別安全：全字串）
├── templates/
│   ├── deployment.yaml     # Go template + 值引用
│   └── _helpers.tpl        # 共用 helper
└── .github/workflows/
    └── chart-ci.yml        # 驗證管線

關鍵檔案內容

x-logging: &logging
  driver: json-file
  options:
    max-size: "10m"

x-resources: &res
  requests: {cpu: "100m", memory: "128Mi"}

app:
  replicas: 1
  logging: <<: *logging
  resources: <<: *res

app:
  replicas: 5
  resources:
    requests: {cpu: "500m", memory: "512Mi"}
  logging:
    options:
      max-size: "100m"   # 只覆寫一層

$ helm lint myapp-chart -f myapp-chart/values-prod.yaml
==> Linting myapp-chart
[INFO] Chart.yaml: icon is recommended
1 chart(s) linted, 0 chart(s) failed

$ helm template myapp myapp-chart -f myapp-chart/values-prod.yaml | yq '.spec.replicas'
5

$ helm-docs   # 從 values.yaml 產生 README 表格
README.md generated

關鍵洞察：錨點在此負責「共用基底」，環境差異交給 Helm 的 values 覆寫——兩者分工，values.yaml 保持單一事實來源，values-prod.yaml 只寫差異。

② 效能/品質/安全深度

安全：Billion Laughs 攻擊（錨點展開 DoS）

錨點最著名的安全問題是Billion Laughs：巢狀別名會讓記憶體指數爆炸。

a: &x [x,x,x,x]
b: &y [*x, *x, *x, *x]
c: [*y, *y, *y, *y]   # 4×4×4 = 64 元素；10 層就是 4^10

品質：錨點的可追蹤性成本

錨點讓「值從哪來」變難追蹤——*base 背後是哪一段？品質策略：錨點只用於真正的共用基底（team 都認識的片段），不要為單一用途建立錨點；命名要有語意（&logging 優於 &x）；並用 helm lint / yamllint 在 CI 把關。

效能：錨點是省記憶體的技巧

相反地，錨點也能省記憶體：同一棵節樹被引用多次時，解析器只存一份（某些實作會做引用計數）。但對「設定檔」這種小檔案，效果可忽略——錨點的價值在可維護性，不在效能。

③ 站際比較對照表

④ 互動式檢核清單

• 能寫出 &anchor / *alias / <<: *alias 三種用法，並預測解析結果。
• 能解釋合併鍵是淺層合併，並設計一個「覆寫時保住其他子鍵」的對策。
• 能架構一個 Helm chart 的 values 分層（基底 + 環境覆寫），並用 helm template 驗證。
• 能重現 Billion Laughs 概念，並列出至少三種防禦手段。
• 能判斷何時該用錨點、何時該重複寫，並寫出團隊可讀的錨點命名。
• 能把 helm lint / yamllint 接進 CI，防住「錨點誤用」進 main。