YAML 程式碼檢查最佳實踐：部署前捕捉錯誤

YAML 檔案中一個放錯的空格就可能導致正式環境部署失敗。不同於 JSON 會在語法錯誤時大聲報錯，YAML 可能會在不正確的縮排下默默解析出意想不到的資料結構。程式碼檢查能在這些問題到達正式環境之前將其捕捉。

為什麼要對 YAML 進行程式碼檢查？

YAML 的靈活性既是它的優勢也是弱點：

# 這是合法的 YAML，但很可能是錯的
ports:
  - 80
  - 443
  name: webserver  # 這是第二個列表項的鍵，而非映射的鍵！

上面的程式碼會建立一個列表，其中第二個項目是一個映射 {443: null, name: webserver}。程式碼檢查工具會捕捉這個縮排問題。若沒有程式碼檢查，這類錯誤可能需要數小時才能診斷出來。

yamllint：標準的程式碼檢查工具

yamllint 是最廣泛使用的 YAML 程式碼檢查工具。它同時檢查語法正確性和風格一致性。

安裝

pip install yamllint

基本用法

# 檢查單一檔案
yamllint config.yaml

# 檢查整個目錄
yamllint .

# 使用特定設定檔檢查
yamllint -c .yamllint.yml .

設定

在專案根目錄建立 .yamllint.yml：

extends: default

rules:
  line-length:
    max: 120
    level: warning
  indentation:
    spaces: 2
    indent-sequences: true
  truthy:
    allowed-values: ['true', 'false', 'yes', 'no']
  comments:
    require-starting-space: true
    min-spaces-from-content: 2
  document-start: disable
  empty-lines:
    max: 1

主要規則說明

程式碼檢查可捕捉的常見錯誤

1. Tab 字元

YAML 禁止使用 Tab 進行縮排，但編輯器有時會插入它們：

# 錯誤：Tab 字元
server:
port: 8080  # 使用了 Tab 而非空格！

2. 不一致的縮排

# 錯誤：混合使用 2 和 4 個空格的縮排
database:
  host: localhost
    port: 5432  # 錯誤：使用了 4 個空格而非 2 個

3. 重複的鍵

# 錯誤：重複的鍵（第二個會默默覆寫第一個）
server:
  port: 8080
  host: localhost
  port: 9090  # 重複了！到底用哪個 port？

4. 尾隨空白

看不見的尾隨空白可能導致意想不到的行為，尤其是在多行字串中。程式碼檢查工具會立即標記這些問題。

無需安裝任何工具就能快速驗證：將你的 YAML 貼到我們的 YAML 驗證器中。

CI/CD 整合

GitHub Actions

name: YAML Lint
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install yamllint
        run: pip install yamllint
      - name: Lint YAML files
        run: yamllint .

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/adrienverge/yamllint
    rev: v1.33.0
    hooks:
      - id: yamllint
        args: [-c, .yamllint.yml]

pip install pre-commit
pre-commit install

現在每次提交前 YAML 都會自動進行程式碼檢查。

GitLab CI

yaml-lint:
  image: python:3.12-slim
  script:
    - pip install yamllint
    - yamllint .
  rules:
    - changes:
        - "**/*.yaml"
        - "**/*.yml"

編輯器整合

大多數編輯器支援即時 YAML 程式碼檢查：

• VS Code：安裝 Red Hat 的 "YAML" 擴充功能（使用 yamllint）
• Vim/Neovim：使用 ALE 或 coc-yaml
• JetBrains IDE：內建 YAML 支援，可設定檢查項目

為 YAML 檔案啟用儲存時自動格式化，以自動修正空白問題。

工具特定的程式碼檢查

通用的 YAML 程式碼檢查可捕捉語法錯誤，但工具特定的檢查工具能驗證語意正確性：

Kubernetes

# kubeval - 根據 K8s 結構描述驗證
kubeval deployment.yaml

# kubeconform - 更快的替代方案
kubeconform -strict deployment.yaml

Docker Compose

docker compose config --quiet

GitHub Actions

# actionlint - 驗證工作流程語法
actionlint .github/workflows/*.yml

Ansible

ansible-lint playbook.yml

若想更深入了解 YAML 語法規則，請參閱我們的 YAML 語法教學。

最佳實踐摘要

1. 將 yamllint 加入 CI — 每次 YAML 變更都應通過程式碼檢查
2. 使用 pre-commit hook — 在錯誤到達儲存庫之前就捕捉
3. 統一使用 2 個空格的縮排 — DevOps 的慣例
4. 停用或限制 truthy 規則 — yes/no 的布林值問題會造成真實的錯誤
5. 設定合理的行長度限制 — 120 字元適用於大多數情況
6. 使用工具特定的驗證器 — 通用檢查加上 K8s/Docker/Actions 特定的驗證
7. 設定你的編輯器 — 即時回饋比 CI 失敗更快速

常見問題

設定檔應該使用 YAML 還是 JSON？

YAML 因其可讀性、註解支援和簡潔的語法，更適合用於人工編輯的設定檔。JSON 則更適合機器產生的資料和 API 通訊。若需要詳細比較，請參閱我們的 YAML vs JSON 指南。

如何處理 yamllint 的警告與錯誤？

將關鍵規則（縮排、語法）設為會阻擋 CI 的錯誤。將風格規則（行長度、註解）設為會顯示但不阻擋的警告。這在嚴格性與開發者生產力之間取得平衡。

相關資源

• YAML 驗證器 — 線上即時驗證 YAML 語法
• YAML 語法教學 — 從零開始學習 YAML
• YAML 與 Docker Compose — Docker 專用 YAML 模式