YAML/JSON 設定檔互轉指南：DevOps 與開發必備

YAML vs JSON：為什麼需要互轉？

場景	常用格式	原因
Docker Compose	YAML	人類可讀、支援註解
Kubernetes	YAML	官方推薦
GitHub Actions	YAML	工作流程定義
API 請求/回應	JSON	機器解析
package.json	JSON	Node.js 標準
tsconfig.json	JSON	TypeScript 標準
Cargo.toml	TOML	Rust 標準

開發者經常需要在 YAML（設定檔）和 JSON（API/程式）之間轉換。

---

使用工具庫互轉

YAML ↔ JSON

1. 開啟 YAML ↔ JSON 工具
2. 貼上 YAML 或 JSON
3. 自動轉換並格式化
4. 複製結果

TOML ↔ JSON

1. 開啟 TOML ↔ JSON 工具
2. 貼上 TOML 或 JSON
3. 自動轉換

---

語法差異

YAML 特性（JSON 不支援）

# 註解 — JSON 不支援
name: toolsku
version: 1.0
port: 3000          # 數字不需要引號
tags:               # 陣列
  - pdf
  - image
database:
  host: localhost   # 巢狀物件
  port: 5432
enabled: true       # 布林值
empty: null         # 空值
multiline: |        # 多行字串
  這是第一行
  這是第二行

等價 JSON：

{
  "name": "toolsku",
  "version": "1.0",
  "port": 3000,
  "tags": ["pdf", "image"],
  "database": { "host": "localhost", "port": 5432 },
  "enabled": true,
  "empty": null,
  "multiline": "這是第一行\n這是第二行"
}

---

常見陷阱

1. YAML 的隱式型別轉換

# ⚠️ 危險：YAML 1.1 會將以下值解析為布林/空值
country: NO    # → false (挪威國家碼被誤解!)
version: 1.0   # → 1.0 (float)
date: 2024-01-01  # → 可能被解析為日期

解決：對可能被誤解的值加引號 "NO"、"1.0"。

2. 縮排必須使用空格

# ❌ 混用 Tab 和空格
name: test
	tags: [a, b]  # Tab 縮排 → 解析錯誤

# ✅ 統一 2 空格縮排
name: test
  tags: [a, b]

3. JSON 不支援註解

// ❌ JSON 中不能寫註解
{ "name": "test" /* 註解 */ }

需要註解時使用 YAML，或使用 JSON 格式化工具 的 JSON5 模式。

---

實戰場景

Docker Compose → JSON（程式讀取）

# docker-compose.yml
services:
  web:
    image: nginx:latest
    ports: ["8080:80"]

→ 轉為 JSON 供 Node.js 程式解析設定

Kubernetes YAML 除錯

# 將 K8s YAML 轉為 JSON 後用 jq 查詢
kubectl get pod my-pod -o json | jq '.status.phase'

使用 JSONPath 工具 也可以直接從 JSON 中提取欄位。

CI/CD 設定驗證

轉換 YAML 為 JSON 後，用 JSON 格式化工具 驗證語法是否正確。

---

總結

YAML/JSON/TOML 互轉是 DevOps 和全端開發的日常需求。工具庫提供 YAML↔JSON、TOML↔JSON 和 JSON 格式化 工具，瀏覽器本機處理，即時轉換，免費使用。