JSON 轉 YAML 比較：Kubernetes、Docker Compose、Ansible 實務

Q: YAML 輸出中埠號 8080 會變成字串嗎？

不會。YAML 把沒有引號的數值當數值處理。實際出問題的是相反情況：JSON 的字串 "8080" 在 YAML 中被輸出為沒有引號的 8080，下次轉換時變成數值。要保留原始字串型別，需要使用會對模糊值加引號的轉換器。yq v4 和最新 PyYAML 都能正確處理。

Q: PyYAML 為什麼把欄位按字母排序？

PyYAML 的 yaml.dump 預設值為 sort_keys=True。指定 sort_keys=False 就能保留原始 JSON 的欄位順序。Kubernetes 資源中要讓 apiVersion 在最前面，這是必備選項。

Q: Helm values.json 能轉成 values.yaml 嗎？

可以。values 的資料結構完全相同，只是檔案格式不同。用 yq -P '.' values.json > values.yaml 轉換後，可以用 helm template ./chart -f values.yaml > rendered.yaml 驗證渲染結果。

Q: YAML 的 null 顯示為 `~` 符號

YAML 表達 null 的方式有 null、Null、NULL、~、空值等好幾種。不同轉換工具採用的預設表示不同。yq 用 null，PyYAML 預設空值，js-yaml 用 null。全部意義相同，只是外觀差異。要強制特定表示： ``python yaml.add_representer(type(None), lambda d, _: d.represent_scalar("tag:yaml.org,2002:null", "null")) ``

Q: JSON 的 anchor 會保留在 YAML 輸出中嗎？

JSON 規格沒有 anchor 概念。要在 YAML 輸出中使用 anchor（&anchor / *alias），必須在轉換後手動加上，或使用支援 YAML 的編輯器。ruamel.yaml 支援程式化產生 anchor。

Q: 沒有網路連線時怎麼把 JSON 轉 YAML？

本機環境有三種方法：第一，安裝無依賴的 Go 單二進位檔 yq。第二，執行使用 pyyaml 的 Python 腳本。第三，撰寫使用 js-yaml 的 Node.js 腳本。FormatArc JSON to YAML 轉換器 網頁載入一次後就在瀏覽器內運作，不需要額外網路連線也能使用。

TL;DR — 依用途選方法，10 秒速查

現在就要轉、不裝東西 → FormatArc JSON to YAML（瀏覽器內完成、不需上傳、驗證 JSON 語法、保留欄位順序）
CLI / 一列指令 → yq -P '.' file.json（DevOps 標準工具，-P 指定區塊格式）
Python 腳本 + 保留欄位順序 → yaml.dump(data, sort_keys=False, default_flow_style=False, allow_unicode=True)
Node.js 應用 → js-yaml 的 yaml.dump(data, { lineWidth: -1 })
Go 服務 → gopkg.in/yaml.v3 的 yaml.Marshal
Kubernetes 來回轉換 → kubectl get ... -o json | jq '...' | yq -P '.'
JSON 陣列拆成多文件 YAML → yq -P '.[]' --split-exp 'true' array.json

方法	安裝準備	保留欄位順序	區塊標量（`\|`）	多文件輸出	插入註解
FormatArc 瀏覽器	無	支援	支援	不支援	不支援（轉換後手動加）
`yq -P '.'`	`brew install yq`	支援	支援	支援（`split-exp`）	不支援
Python `yaml.dump`（PyYAML）	`pip install pyyaml`	需 `sort_keys=False`	支援	手動 `---` 分隔	不支援
Python `ruamel.yaml`	`pip install ruamel.yaml`	支援	支援	支援	支援（API 操作）
Node `js-yaml`	`npm install js-yaml`	支援	支援	手動	不支援
Go `yaml.Marshal`	`go get gopkg.in/yaml.v3`	支援（經 `yaml.Node`）	支援	`Encoder` 迴圈	不支援

JSON 轉 YAML 在結構層面很直接（兩種格式表現同一套資料模型）。實務上棘手的部分是：欄位順序的保留、字串引號的判斷、多行文字的處理、JSON 陣列拆成多文件 YAML、以及避免 Norway 問題等實作細節。

為什麼要把 JSON 轉成 YAML

JSON 和 YAML 都能表達相同的資料結構（map/物件、list/陣列、字串、數值、布林值、null）。功能上互換，但選擇哪個格式通常取決於執行環境的生態系與可讀性。型別、註解、錨點等細節上的差異，可參考 YAML JSON 比較：型別、註解、錨點與 4 種解析器的實測差異。

Kubernetes 與容器編排

Kubernetes 同時接受 JSON 和 YAML 作為資源定義，但生態系壓倒性地以 YAML 為主。官方文件、教學、技術部落格、社群回答幾乎全是 YAML。用程式產生的資源定義（多半是 JSON）轉成 YAML 後，跟叢集設定保持一致，pull request 的審查也順暢很多。

kubectl 有 YAML 輸出的旗標：

kubectl get deployment web-app -o yaml > deployment.yaml

但當來源檔案（source of truth）是 JSON 時（admission controller webhook 回應、Terraform Kubernetes provider 的輸出、自訂 operator 的 reconciliation 結果等），就需要顯式轉換。

Docker Compose 與 Helm values

Docker Compose 檔案的標準格式就是 YAML。如果服務設定是以 JSON 形式提供的（来自 configuration management API 或 service mesh control plane），在使用前需要先轉成 YAML。

Helm chart 的 values.yaml 也是 YAML。從 HashiCorp Vault 或 AWS Systems Manager Parameter Store 等外部來源取得設定時（回傳 JSON），要在 helm install -f values.yaml 之前轉成 YAML。

Ansible playbook

Ansible playbook 和 inventory 檔案都是 YAML 格式。雲端 API、CMDB、資產管理資料庫匯出的資料通常是 JSON，所以 playbook 使用前第一步就是轉 YAML。

可讀性與編輯便利

YAML 對人來說是最好讀寫的形式。沒有花括號（{}）、方括號（[]）、逗號（,）這些符號，視覺雜訊少很多。

JSON：

{
  "server": {
    "host": "0.0.0.0",
    "port": 8080,
    "workers": 4,
    "logging": {
      "level": "info",
      "format": "json"
    }
  }
}

YAML：

server:
  host: 0.0.0.0
  port: 8080
  workers: 4
  logging:
    level: info
    format: json

YAML 版字元數較少，階層結構用縮排直觀呈現。工程師經常查看和修改的設定檔，這個可讀性差異會帶來很大的效率提升。

加入註解

JSON 規格沒有註解語法。YAML 則標準支援 # 註解。想在設定檔裡記錄某個值的意圖或注意事項，就轉成 YAML 後加註解：

server:
  host: 0.0.0.0
  port: 8080
  # 生產環境要增加 workers 數，staging 用 4 個就夠
  workers: 4

JSON 轉 YAML 常作為「在設定檔加說明」的第一步。註解本身無法從 JSON 帶過來（JSON 沒有註解語法）。如果一定要在 JSON 端表現，可參考 JSON 註解的替代方法。

JSON 轉 YAML 的 4 個實務場景

場景 1：Kubernetes API 回應存入 Git manifest

Kubernetes API 回傳 JSON。要把 Deployment 狀態以 YAML 檔 commit 到 GitOps 倉庫：

kubectl get deployment web-app -o json | yq -P '.' > deployment.yaml
git add deployment.yaml && git commit -m "Capture web-app current state"

場景 2：Vault secret 轉 Helm values

Vault 以 JSON 回傳 secret，Helm 需要 values.yaml：

vault read -format=json secret/prod/app | jq '.data.data' | yq -P '.' > values.yaml
helm upgrade --install app ./chart -f values.yaml

場景 3：control plane API 轉 Docker Compose

service mesh 的 control plane 以 JSON 回傳服務定義，Docker Compose 需要 YAML：

curl -s https://control-plane/services | jq '.' | yq -P '.' > docker-compose.yml
docker compose up -d

場景 4：CMDB 轉 Ansible inventory

多數 CMDB（Device42、ServiceNow、NetBox 等）透過 REST API 回傳 JSON。Ansible inventory 是 YAML：

curl -s https://cmdb/hosts | jq '.hosts' | yq -P '.' > inventory.yaml
ansible-playbook -i inventory.yaml site.yaml

四個場景都是單步驟 pipeline，自動化腳本很好寫。

瀏覽器內完成 vs 雲端轉換：上傳設定檔的安全風險

市面上很多線上 JSON 轉 YAML 轉換器宣稱「client-side 處理」，實際上卻把輸入資料 POST 到後端伺服器。設定檔的情況特別危險，因為通常包含：

secret: 區塊的 API token 與認證資料
含密碼的資料庫連線字串（connection string）
雲端存取金鑰（AWS IAM、GCP service account JSON）
內部 hostname 與基礎架構網路結構
加密金鑰與 TLS 憑證

就算宣稱「不留 log」，伺服器端一個小設定疏失就可能讓 secret 外洩。用瀏覽器內完成、不會把資料送到伺服器的工具才安全。

這不是假設。2025 年 11 月，資安公司 watchTowr 報告，大型線上格式化與轉換網站 JSONFormatter 和 CodeBeautify 中，使用者儲存的資料透過「Recent Links」功能處於任何人都能檢視的狀態。收集的提交物超過 8 萬筆（5GB 以上），包含 Active Directory 認證、資料庫與雲端存取金鑰、私人金鑰、CI/CD secret、JWT 與 API token、金流 gateway 認證資訊、AWS Secrets Manager 完整匯出資料，影響政府、金融、醫療、航太等各種機構（watchTowr 調查報告在新分頁中開啟）。把資料貼進會儲存或傳輸輸入的轉換器，同樣有暴露風險。

確認方法：打開轉換器網頁，在開發者工具（F12）的 Network 分頁勾選「Offline（停用網路）」，然後貼上 JSON。工具能正常運作代表是瀏覽器內處理；卡住或出現網路錯誤則是雲端傳輸方式。線上轉換工具使用前該做的隱私檢查，整理在線上安全：轉換工具使用前必做的 5 項隱私檢查（2025 年外洩事件）。

FormatArc JSON to YAML 轉換器在離線狀態下也能完整運作。本機 CLI 工具 yq 或本機 Python/Node.js/Go 腳本同樣安全。

Kubernetes Secret、含 API token 的 Helm values、含認證的設定檔，務必用瀏覽器內工具或本機環境轉換。

方法 1：FormatArc 瀏覽器工具（不需安裝與上傳）

JSON to YAML 轉換器把 JSON 轉成整齊的 YAML。所有處理都在瀏覽器內完成。

打開 JSON to YAML 轉換器。
在左側編輯器貼上 JSON。
點「轉換」按鈕。

FormatArc JSON to YAML 轉換結果

這個工具在轉換前會驗證 JSON 的有效性。漏逗號、多餘的閉括號（}）、沒有引號的 key 等語法錯誤，會附上行號即時顯示。即使目的不是轉 YAML，也能當快速 JSON 驗證器用。常見 JSON 解析錯誤的原因與修法，可參考 JSON 解析錯誤的原因與修法。

因為只在瀏覽器內執行，處理認證資訊或內部基礎架構設定等敏感資料時也可以安心使用。

輸出結果採用 Kubernetes 標準的 2 空格縮排，保留輸入 JSON 的欄位順序，預設使用區塊樣式（沒有花括號的標準 YAML 外觀）。

方法 2：yq（DevOps 標準 CLI 工具）

yq 是終端機環境中處理 JSON 轉 YAML 最流暢的工具。

# 基本轉換
yq -P '.' input.json > output.yaml

# 從標準輸入（stdin）管線接收
cat config.json | yq -P '.' > output.yaml

# 區塊格式（可讀性高的標準 YAML）；沒有 -P 可能會輸出 flow 格式
yq -P '.' input.json

# 指定縮排寬度（預設 2）
yq -P -I=4 '.' input.json

# 只提取特定子樹再轉換
yq -P '.spec.template' deployment.json

# JSON 陣列拆成多文件 YAML 輸出
yq -P '.[]' --split-exp 'true' kubernetes-list.json

-P 是 --prettyPrint 的簡寫，強制 YAML 以區塊格式輸出。沒有 -P 時，巢狀結構可能以 flow 格式（類似 JSON 的外觀）輸出。

安裝方式：

# macOS（Homebrew）
brew install yq

# Linux（直接安裝二進位檔）
sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
sudo chmod +x /usr/local/bin/yq

# Docker
docker run --rm -i mikefarah/yq -P '.' < input.json > output.yaml

yq + jq 組合：邊過濾邊轉換

# 從 Deployment 只提取 spec.template 再轉 YAML
jq '.spec.template' deployment.json | yq -P '.'

# yq 單獨也能處理
yq -P '.spec.template' deployment.json

流水線已有 Node.js 的環境，也可以免安裝用 npx formatarc json-to-yaml 一列指令完成轉換，不用另外安裝二進位檔。用法整理在 formatarc npm。

方法 3：Python（PyYAML 與 ruamel.yaml）

PyYAML 基本用法

import json
import yaml

with open("config.json") as f:
    data = json.load(f)

with open("config.yaml", "w") as f:
    yaml.dump(
        data,
        f,
        default_flow_style=False,   # 區塊格式（標準 YAML 樣式）
        allow_unicode=True,          # 不將 Unicode 字元轉成 \uXXXX
        sort_keys=False,             # 保留輸入 JSON 的欄位順序
    )

必須指定的三個核心選項：

default_flow_style=False — 輸出區塊 YAML，而不是 {a: 1, b: 2} 這種一列 flow 格式。
allow_unicode=True — 中文、特殊符號、表情符號等不會被轉成 \uXXXX，保持人可讀的文字。
sort_keys=False — 保留 JSON 原本的欄位順序（Kubernetes 中 apiVersion 必須在 kind 前面，所以這是必需的）。

終端機一列指令

python3 -c 'import sys, json, yaml; yaml.dump(json.load(sys.stdin), sys.stdout, default_flow_style=False, allow_unicode=True, sort_keys=False)' < input.json > output.yaml

用 ruamel.yaml 保留註解與格式

需要在產出的 YAML 中程式化加入註解，或精細控制格式時，用 ruamel.yaml：

from ruamel.yaml import YAML
import json

yaml_writer = YAML()
yaml_writer.default_flow_style = False
yaml_writer.preserve_quotes = True
yaml_writer.indent(mapping=2, sequence=4, offset=2)

with open("config.json") as fin:
    data = json.load(fin)

# 程式化加入註解
data.yaml_set_comment_before_after_key("server", before="Web server 設定")

with open("config.yaml", "w") as fout:
    yaml_writer.dump(data, fout)

需要精細控制註解或引號格式時，ruamel.yaml 是最佳選擇。

方法 4：Node.js（js-yaml）

const fs = require("fs");
const yaml = require("js-yaml");

const data = JSON.parse(fs.readFileSync("config.json", "utf8"));
const ymlText = yaml.dump(data, {
  lineWidth: -1,    // 防止長行自動換行
  noRefs: true,     // 不產生 YAML anchor 與 alias
  sortKeys: false,  // 保留輸入順序
  quotingType: '"', // 需要引號時優先使用雙引號
});

fs.writeFileSync("config.yaml", ymlText);

lineWidth: -1 阻止 js-yaml 的自動換行行為，避免長 URL 或設定字串在中間斷行。noRefs: true 關閉 anchor 產生，提高與 kubectl 等不支援 anchor 的下游工具的相容性。

方法 5：Go（gopkg.in/yaml.v3）

package main

import (
    "encoding/json"
    "fmt"
    "os"

    "gopkg.in/yaml.v3"
)

func main() {
    data, _ := os.ReadFile("config.json")
    var obj interface{}
    json.Unmarshal(data, &obj)
    out, _ := yaml.Marshal(obj)
    fmt.Print(string(out))
}

Go 中要確保欄位順序保留，必須用 yaml.Node 而不是 interface{}。用 json.Unmarshal 解成 map[string]interface{} 後，Go map 的內部特性會把順序打亂。Kubernetes manifest 這種欄位順序很重要的場景會出問題。

// 要明確保留順序就用 yaml.Node
var node yaml.Node
yaml.Unmarshal(data, &node)
out, _ := yaml.Marshal(&node)

也可以用維持插入順序的第三方函式庫（如 github.com/iancoleman/orderedmap）。

Kubernetes Deployment 實例：JSON 與 YAML 來回轉換

實際工作場景。從 JSON 格式的 Deployment 資源定義開始：

{
  "apiVersion": "apps/v1",
  "kind": "Deployment",
  "metadata": {
    "name": "web-app",
    "labels": { "app": "web", "tier": "frontend" }
  },
  "spec": {
    "replicas": 3,
    "selector": { "matchLabels": { "app": "web" } },
    "template": {
      "metadata": { "labels": { "app": "web" } },
      "spec": {
        "containers": [{
          "name": "nginx",
          "image": "nginx:1.25",
          "ports": [{ "containerPort": 80 }],
          "env": [
            { "name": "LOG_LEVEL", "value": "info" }
          ]
        }]
      }
    }
  }
}

用 yq 轉換：

yq -P '.' deployment.json

輸出：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-app
  labels:
    app: web
    tier: frontend
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: nginx
          image: nginx:1.25
          ports:
            - containerPort: 80
          env:
            - name: LOG_LEVEL
              value: info

apiVersion → kind → metadata → spec 的順序完美保留。如果用 PyYAML 預設設定（sort_keys=True）執行，會依字母順序排列，kubectl apply 本身能通過，但跟上游 Kubernetes 範例的 Git diff 會亂掉，代碼審查變得很辛苦。

套用：kubectl apply -f deployment.yaml

YAML 字串引號處理：「8080」變成數值 8080 的問題

YAML 判斷字串是否需要引號的規則非常複雜。轉換器處理過程中可能產生非預期的型別轉換。YAML 的基本語法與常見錯誤的解決方法，整理在 YAML 語法教學：縮排規則、型別與常見錯誤解決。

數字形式的字串被去掉引號

JSON 中把埠號以 "8080" 字串保存，轉換器卻在 YAML 中擅自去掉引號變成數值：

JSON：

{ "port": "8080" }

正確的轉換結果：

port: "8080"   # 維持字串型別

錯誤的轉換結果：

port: 8080     # 被改成數值了

yq v4、PyYAML（預設設定）、js-yaml 都會正常保留原始字串型別。用正則或 heuristic 自制的轉換腳本最容易出這個問題。

PyYAML 中要強制特定字串加引號，可以定義 wrapper：

class QuotedString(str): pass

def represent_quoted(dumper, data):
    return dumper.represent_scalar("tag:yaml.org,2002:str", str(data), style='"')

yaml.add_representer(QuotedString, represent_quoted)

看起来像布林值的字串（Norway 問題）

{ "active": "yes" }

轉成 YAML 1.1 schema 時：

active: yes    # 下次解析時會被解讀成布林值 true

品質有把關的轉換器會安全地加上引號：

active: "yes"

如果能控制原始 JSON，用 JSON 標準型別 true / false / null 取代 "yes" / "no" 這類字串，就能從根本上避免 Norway 問題（國家代碼 NO 被轉成 false 的 bug 等）。

以特殊字元開頭的字串

YAML 特殊字元（*、&、!、{、[、>、|、#、@、`、開頭的 -）開頭的值必須加引號：

{ "tag": "*production*" }

tag: "*production*"   # 因為開頭的 * 所以加引號

主要轉換工具都會自動安全處理。

區塊標量：多行文字的 | 與 > 記法

JSON 用 \n 逸出字元表達多行文字。轉 YAML 時，使用可讀性高的區塊標量（Block Scalar）記法是一般做法。

JSON：

{
  "description": "Line one\nLine two\nLine three"
}

YAML 有三種表達方式：

字面區塊（|）— 保留原始換行

description: |
  Line one
  Line two
  Line three

來源的換行在輸出字串中原封不動。最適合 log 訊息、憑證 PEM 區塊、設定檔中內含的 shell 腳本。

摺疊區塊（>）— 換行變空白

description: >
  Line one
  Line two
  Line three

這種方式會被解讀為 Line one Line two Line three 單一句子（換行變空白，只有空行才當作實際換行）。適合段落式的長說明文字。

引號封單一字串

description: "Line one\nLine two\nLine three"

雙引號內直接用 \n 逸出。能運作但超過 2～3 行就很難讀。

yq -P 對含換行的字串預設使用 |（字面）方式。PyYAML 和 js-yaml 預設也是 |。

PyYAML 中要強制特定樣式：

yaml.dump(data, default_style='|')   # 所有字串都用字面區塊
yaml.dump(data, default_style='"')   # 所有字串都用雙引號

包含多行腳本或 PEM 憑證的 Kubernetes ConfigMap 必須用 | 方式。kubectl create configmap --from-file 也產生 | 格式的 manifest。

欄位順序保留：維持 apiVersion、kind、metadata 順序

JSON 物件和 YAML mapping 在規格上都是無順序（unordered）結構。但實際運作環境要求有意義的順序。特別是 Kubernetes 資源中，apiVersion → kind → metadata → spec 的慣例順序已經確立。

主要工具的順序保留現狀：

yq（Go yaml.v3 基礎）：透過內部 yaml.Node 保留順序
PyYAML + sort_keys=False：保留順序（預設值 sort_keys=True 是字母排序，必須顯式設定）
js-yaml + sortKeys: false：保留順序
ruamel.yaml：預設保留順序

注意事項：

PyYAML 預設值 sort_keys=True — 所有 key 字母排序，apiVersion 會被推到 kind 後面
Go 的 interface{} 反序列化 — map 順序-randomized（必須用 yaml.Node）
自寫腳本中經 Go map（map[string]string）輸出 — 順序隨意打亂

把 YAML commit 到 Git 的 GitOps 工作流中，欄位順序隨機變動會產生大量不必要的 Git diff。導入轉換工具到部署 pipeline 前，務必確認欄位順序保留。

JSON 陣列拆成多文件 YAML 輸出

Kubernetes 資源的 JSON 陣列轉成以 --- 分隔的多文件 YAML 檔案，這是一個常見模式。

用 yq

yq -P '.[]' --split-exp 'true' kubernetes-list.json

輸出：

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
---
apiVersion: v1
kind: Service
metadata:
  name: app-service

存檔：yq -P '.[]' --split-exp 'true' kubernetes-list.json > resources.yaml，立即成為 kubectl apply -f resources.yaml 可用的檔案。

用 Python

import json
import yaml

with open("list.json") as f:
    items = json.load(f)["items"]   # 依實際陣列路徑調整

with open("resources.yaml", "w") as f:
    yaml.dump_all(
        items,
        f,
        default_flow_style=False,
        allow_unicode=True,
        sort_keys=False,
    )

yaml.dump_all 函式把每個項目以 --- 分隔輸出為多個文件。

用 Node.js

const yaml = require("js-yaml");
const fs = require("fs");

const items = JSON.parse(fs.readFileSync("list.json", "utf8")).items;
const ymlText = items.map(item => yaml.dump(item, { lineWidth: -1 })).join("---\n");

fs.writeFileSync("resources.yaml", ymlText);

js-yaml 沒有內建 dumpAll，所以用 ---\n 手動拼接。

CI/CD pipeline 整合

GitHub Actions

name: Convert JSON config to YAML for deployment
on:
  push:
    paths: ["config/*.json"]

jobs:
  convert:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install yq
        run: |
          sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
          sudo chmod +x /usr/local/bin/yq
      - name: Convert all configs
        run: |
          for f in config/*.json; do
            yq -P '.' "$f" > "${f%.json}.yaml"
          done
      - name: Validate against Kubernetes
        run: |
          for f in config/*.yaml; do
            kubectl apply --dry-run=client -f "$f"
          done
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "Auto-convert configs to YAML"

GitLab CI

generate-yaml:
  image: mikefarah/yq:latest
  stage: build
  script:
    - for f in config/*.json; do yq -P "." "$f" > "${f%.json}.yaml"; done
  artifacts:
    paths:
      - config/*.yaml

Jenkins（Declarative）

pipeline {
  agent any
  stages {
    stage('Convert configs') {
      steps {
        sh 'for f in config/*.json; do yq -P "." "$f" > "${f%.json}.yaml"; done'
      }
    }
    stage('Validate') {
      steps {
        sh 'for f in config/*.yaml; do kubectl apply --dry-run=client -f "$f"; done'
      }
    }
  }
}

轉換與驗證步驟各只要一條指令，對 pipeline 整體耗時影響很小。

Kubernetes 實務工作流

實務上最常遇到的場景。用 kubectl 把現有資源以 JSON 取得、修改、轉 YAML、commit 到 Git 倉庫：

# 以 JSON 取得目前 Deployment 設定
kubectl get deployment web-app -o json > deployment.json

# 修改值（用 jq 自動修改的範例）
jq '.spec.replicas = 5' deployment.json > updated.json

# 轉 YAML 存到 Git 倉庫
yq -P '.' updated.json > deployment.yaml

# 確認變更、commit、push
git diff deployment.yaml
git add deployment.yaml && git commit -m "Scale web-app to 5 replicas"

一列 pipeline 搞定：

kubectl get deployment web-app -o json | jq '.spec.replicas = 5' | yq -P '.' > deployment.yaml

不需要寫腳本的一次性修改，直接貼到 JSON to YAML 轉換器、複製輸出的 YAML 存成檔案，是最快的方式。

常見問題

YAML 輸出中埠號 8080 會變成字串嗎？

不會。YAML 把沒有引號的數值當數值處理。實際出問題的是相反情況：JSON 的字串 "8080" 在 YAML 中被輸出為沒有引號的 8080，下次轉換時變成數值。要保留原始字串型別，需要使用會對模糊值加引號的轉換器。yq v4 和最新 PyYAML 都能正確處理。

JSON 轉 YAML 時能保留註解嗎？

不能。JSON 沒有註解語法，所以 JSON 轉 YAML 過程中無法保留註解。如果註解對設定檔很重要，應該以 YAML 為來源檔案管理，或在 JSON 端使用替代方案。

PyYAML 為什麼把欄位按字母排序？

PyYAML 的 yaml.dump 預設值為 sort_keys=True。指定 sort_keys=False 就能保留原始 JSON 的欄位順序。Kubernetes 資源中要讓 apiVersion 在最前面，這是必備選項。

Helm values.json 能轉成 values.yaml 嗎？

可以。values 的資料結構完全相同，只是檔案格式不同。用 yq -P '.' values.json > values.yaml 轉換後，可以用 helm template ./chart -f values.yaml > rendered.yaml 驗證渲染結果。

YAML 的 null 顯示為 `~` 符號

YAML 表達 null 的方式有 null、Null、NULL、~、空值等好幾種。不同轉換工具採用的預設表示不同。yq 用 null，PyYAML 預設空值，js-yaml 用 null。全部意義相同，只是外觀差異。要強制特定表示：

yaml.add_representer(type(None), lambda d, _: d.represent_scalar("tag:yaml.org,2002:null", "null"))

JSON 的 anchor 會保留在 YAML 輸出中嗎？

JSON 規格沒有 anchor 概念。要在 YAML 輸出中使用 anchor（&anchor / *alias），必須在轉換後手動加上，或使用支援 YAML 的編輯器。ruamel.yaml 支援程式化產生 anchor。

沒有網路連線時怎麼把 JSON 轉 YAML？

本機環境有三種方法：第一，安裝無依賴的 Go 單二進位檔 yq。第二，執行使用 pyyaml 的 Python 腳本。第三，撰寫使用 js-yaml 的 Node.js 腳本。FormatArc JSON to YAML 轉換器網頁載入一次後就在瀏覽器內運作，不需要額外網路連線也能使用。

反向轉換（YAML 轉 JSON）

YAML 檔案需要轉回 JSON（API 提交、除錯、JSON 專用工具輸入等）時，FormatArc 也有對應的 YAML to JSON 轉換器，用法與本文相同。YAML 轉 JSON 的 8 個陷阱，整理在 YAML 轉 JSON 指南 — 8 個陷阱全避開。

總結

JSON 轉 YAML 是 DevOps、IaC（Infrastructure as Code）、設定管理工作流中必然遇到的作業。依情境選擇以下 5 種方式：

不需安裝、敏感資料：FormatArc JSON to YAML — 瀏覽器內完成、保留欄位順序、附行號的 JSON 語法驗證
CLI / pipeline 自動化：yq -P '.' — DevOps 標準工具、支援過濾與多文件輸出
Python 應用：yaml.dump(data, sort_keys=False, default_flow_style=False, allow_unicode=True)
Node.js 應用：js-yaml 的 yaml.dump 搭配 lineWidth: -1、sortKeys: false 選項
Go 服務：gopkg.in/yaml.v3 的 Marshal 函式，順序保留用 yaml.Node

生產環境必須記住的 4 個要點：Kubernetes 中必備的欄位順序保留、多行文字使用區塊標量（|）記法、處理多個資源時把 JSON 陣列拆成多文件、以及避免 Norway 問題與引號去除導致的非預期型別轉換。

TL;DR — 依用途選方法，10 秒速查

為什麼要把 JSON 轉成 YAML

Kubernetes 與容器編排

Docker Compose 與 Helm values

Ansible playbook

可讀性與編輯便利

加入註解

JSON 轉 YAML 的 4 個實務場景

場景 1：Kubernetes API 回應存入 Git manifest

場景 2：Vault secret 轉 Helm values

場景 3：control plane API 轉 Docker Compose

場景 4：CMDB 轉 Ansible inventory

瀏覽器內完成 vs 雲端轉換：上傳設定檔的安全風險

方法 1：FormatArc 瀏覽器工具（不需安裝與上傳）

方法 2：yq（DevOps 標準 CLI 工具）

yq + jq 組合：邊過濾邊轉換

方法 3：Python（PyYAML 與 ruamel.yaml）

PyYAML 基本用法

終端機一列指令

用 ruamel.yaml 保留註解與格式

方法 4：Node.js（js-yaml）

方法 5：Go（gopkg.in/yaml.v3）

Kubernetes Deployment 實例：JSON 與 YAML 來回轉換

YAML 字串引號處理：「8080」變成數值 8080 的問題

數字形式的字串被去掉引號

看起来像布林值的字串（Norway 問題）

以特殊字元開頭的字串

區塊標量：多行文字的 | 與 > 記法

字面區塊（|）— 保留原始換行

摺疊區塊（>）— 換行變空白

引號封單一字串

欄位順序保留：維持 apiVersion、kind、metadata 順序

JSON 陣列拆成多文件 YAML 輸出

用 yq

用 Python

用 Node.js

CI/CD pipeline 整合

GitHub Actions

GitLab CI

Jenkins（Declarative）

Kubernetes 實務工作流

常見問題

YAML 輸出中埠號 8080 會變成字串嗎？

JSON 轉 YAML 時能保留註解嗎？

PyYAML 為什麼把欄位按字母排序？

Helm values.json 能轉成 values.yaml 嗎？

YAML 的 null 顯示為 ~ 符號

JSON 的 anchor 會保留在 YAML 輸出中嗎？

沒有網路連線時怎麼把 JSON 轉 YAML？

反向轉換（YAML 轉 JSON）

總結

YAML 的 null 顯示為 `~` 符號