YAML 轉 JSON 指南 — 8 個陷阱全避開（Python / yq / 瀏覽器）

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

• 現在就要轉、不裝東西 → FormatArc YAML to JSON（瀏覽器內完成、不需上傳、附行號的錯誤提示）
• CLI / 一列指令 → yq -o=json '.' file.yaml（DevOps 事實標準）
• Python 腳本與管線 → python3 -c 'import sys, yaml, json; json.dump(yaml.safe_load(sys.stdin), sys.stdout, indent=2)' < file.yaml
• Node.js 應用 → js-yaml 的 yaml.load + JSON.stringify
• Go 服務 → gopkg.in/yaml.v3 + encoding/json
• Kubernetes 來回轉換 → kubectl get ... -o json | yq -P '.'（轉回 YAML）
• 多文件 YAML（--- 分隔的多份文件） → yq -o=json '.' file.yaml（yq 預設會分割）或 NDJSON 輸出

YAML 轉 JSON 的轉換本身通常一行代碼就夠了。真正棘手的部分是 8 個陷阱：Norway 問題、註解遺失、多文件處理、yaml.load 的保安風險、整數鍵變成字串、錨點展開、1.0 變成浮點數、型別推斷依 schema 而異。這篇文章會用 before/after 實例逐一講解。

為什麼要把 YAML 轉成 JSON

實務上常遇到的場景：

• Kubernetes API 提交：YAML manifest 要透過 Kubernetes API POST 時，API 端點只接受 JSON 編碼的 body。
• YAML 結構除錯：YAML 以縮排表達巢狀結構，有時候不容易看對。轉成 JSON 後結構一目了然，漏掉的 - 或縮排錯誤馬上就會浮現。
• JSON 專用工具鏈：下游系統（其他語言的 JSON parser、存 JSON 欄位的資料庫、帶 JSON Schema 驗證的事件匯流排）不接受 YAML 格式。
• 設定審計與保安掃描：把倉庫裡的 YAML 設定檔轉成 JSON 後做 diff 分析、JSON Schema 驗證、或餵給保安掃描器。
• LLM 上下文傳遞：把結構化設定餵給 LLM 時，JSON 的物件邊界比 YAML 的縮排更穩定，模型更容易正確識別。詳見 LLM Markdown vs HTML。

兩種格式的結構差異與完整比較，建議直接翻 YAML JSON 比較 的那篇（同站）。各格式的基本概念與型別系統也值得先過一遍再進入轉換細節，例如 YAML 是什麼？ 與 JSON 是什麼檔案？。

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

不想裝任何東西、快速轉一下的話，YAML to JSON 最快。所有運算在瀏覽器內部執行，資料不會傳到外部伺服器。

1. 打開 YAML to JSON 頁面。
2. 在左側編輯器貼上 YAML 內容。
3. 按「轉換」按鈕，右側即顯示 JSON 結果。

這個工具在轉換時會即時驗證 YAML 語法。縮排錯誤、漏掉的冒號、該用空格的位子用了 Tab 等等，都會附行號報出，所以就算主要目的不是轉換，也能拿來當 YAML 除錯工具用。YAML 語法基礎詳見 YAML 語法教學。

瀏覽器內處理在碰到敏感資料時特別有用。Kubernetes Secret（就算經過 base64 編碼仍是機密資料）、Ansible vault 裡的雲端憑證、包含 API token 的 CI 設定檔——貼上之後資料就留在這個分頁裡，不會外洩。

這不是理論上的憂慮。2025 年 11 月，保安公司 watchTowr 報導指出，知名線上格式化工具 JSONFormatter 與 CodeBeautify 的「儲存」功能存在漏洞，導致超過 5GB 的使用者輸入資料（包含憑證、私密金鑰、API token）處於任何人皆可瀏覽的狀態（watchTowr 調查報告在新分頁中開啟）。瀏覽器內完結的工具不儲存、不傳送輸入，從源頭上就不存在洩漏風險。

線上轉換工具的隱私安全詳見 線上安全：5 項隱私檢查。

瀏覽器工具能正確處理：多行字串（block scalar | 與 folded scalar >）、錨點與別名（inline 展開）、任意深度的巢狀結構、混合型別陣列、null / 布林值 / 數值型別。

方法 2：yq（DevOps 事實標準）

yq 是 YAML 版的 jq，輕量級的命令列處理器。在 DevOps 管線中把 YAML 轉 JSON 時，最常被用到的就是它。

# 基本轉換
yq -o=json '.' input.yaml

# 從 stdin 管線讀入
cat config.yaml | yq -o=json '.'

# 存成檔案
yq -o=json '.' config.yaml > config.json

# 壓縮成單行輸出
yq -o=json -I=0 '.' config.yaml

# 只抽取子樹再轉
yq -o=json '.spec.template' deployment.yaml

# 過濾同時轉換
yq -o=json '.items[] | select(.kind == "ConfigMap")' multi.yaml

安裝方式：

# macOS
brew install yq

# Linux (snap)
snap install yq

# Linux（直接下載 binary）
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

# Go install
go install github.com/mikefarah/yq/v4@latest

注意：叫 yq 的工具其實有兩種。這裡講的是 Mike Farah 用 Go 寫的那個（Kubernetes / CNCF 生態系中到處都是）。kislyuk 的 Python 版 yq 語法不同。2026 年目前的事實標準是 Go 版。

yq 處理多文件 YAML

# 多文件 YAML（--- 分隔的多份文件）
yq -o=json '.' multi.yaml          # 每份輸入文件輸出一份 JSON
yq -o=json -I=0 '.' multi.yaml      # NDJSON 格式（一行一份文件）
yq eval-all '[.]' -o=json multi.yaml  # 把所有文件包成單一 JSON 陣列

Kubernetes manifest 合集要轉成一個 JSON 陣列時，這是最乾淨的做法。

方法 3：Python（彈性最高）

Python 的標準函式庫內建 json 模組，pyyaml 在大多數環境也能直接安裝（pip install pyyaml）。

Python 一列指令

python3 -c 'import sys, yaml, json; json.dump(yaml.safe_load(sys.stdin), sys.stdout, indent=2)' < input.yaml > output.json

從 stdin 讀 YAML，用 yaml.safe_load 解析，再以 indent=2 的格式寫出 JSON 到 stdout。

Python 腳本（多文件與錯誤處理）

import sys
import yaml
import json

with open("config.yaml") as f:
    data = yaml.safe_load(f)  # 多文件時改用 safe_load_all()

with open("config.json", "w", encoding="utf-8") as f:
    json.dump(data, f, indent=2, ensure_ascii=False)

這裡一定要用 yaml.safe_load。預設的 yaml.load 允許建立任意 Python 物件，碰到惡意 YAML 檔會有遠端代碼執行的風險。

Python + ruamel.yaml（結構保留度最高）

想盡量保留引號風格、鍵的順序、註解資訊的話，用 ruamel.yaml（不過 JSON 標準本身不支援註解，所以輸出 JSON 時註解仍會遺失）：

from ruamel.yaml import YAML
import json
import sys

yaml_parser = YAML(typ="safe")
data = yaml_parser.load(open(sys.argv[1]))
json.dump(data, sys.stdout, indent=2, ensure_ascii=False)

大多數一般用途 pyyaml.safe_load 就夠了。需要精確保留 YAML 格式來做 round-trip 時才考慮 ruamel.yaml。

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

Node.js 環境下 js-yaml 是標準選擇。

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

// 單份文件
const doc = yaml.load(fs.readFileSync("config.yaml", "utf8"));
fs.writeFileSync("config.json", JSON.stringify(doc, null, 2));

// 多文件
const docs = yaml.loadAll(fs.readFileSync("multi.yaml", "utf8"));
fs.writeFileSync("multi.json", JSON.stringify(docs, null, 2));

安裝：npm install js-yaml 或 yarn add js-yaml。JSON 排版的實務技巧詳見 JSON 排版線上工具。

處理不受信任的外部 YAML 輸入時，建議用 yaml.load(text, { schema: yaml.JSON_SCHEMA }) 限制為 JSON 相容型別。預設的 DEFAULT_SCHEMA 包含 YAML 1.1 的某些特殊行為（例如 Norway 問題）。

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

package main

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

    "gopkg.in/yaml.v3"
)

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

yaml.v3 是 go-yaml 團隊維護的版本，Kubernetes 內部也用它。注意：YAML 的整數鍵（123: foo）轉成 JSON 時會變成字串（"123": "foo"），因為 JSON 物件的鍵只能是字串。

要串流處理大規模多文件 YAML，用 yaml.NewDecoder 迴圈：

dec := yaml.NewDecoder(file)
for {
    var doc interface{}
    if err := dec.Decode(&doc); err != nil {
        if err == io.EOF { break }
        log.Fatal(err)
    }
    out, _ := json.Marshal(doc)
    fmt.Println(string(out))   // NDJSON：一份文件一行
}

這樣可以用恆定的記憶體用量處理任意大小的多文件 YAML。

YAML 轉換時要注意的 8 個陷阱

YAML 與 JSON 的資料模型並非完全 1:1 對映。以下是在實務中最常踩到的 8 個問題。

陷阱 1：Norway 問題（NO 變 false）

YAML 1.1 規格會把特定沒有引號的字串解析為布林值。

country: NO

轉換結果：

{ "country": false }

NO、no、Off、OFF、n、N、False、f、F 全都會被解析成 false。反過來，YES、Y、On、True、T、t 全都會變成 true。因為國家碼列表裡寫了 country: NO（挪威的 ISO 3166-1 alpha-2 代碼）會自動變成布林值這件事太經典，所以被稱為「Norway 問題」。

解法：可能產生歧義的字串一定加引號。

country: "NO"

YAML 1.2（Core schema）已經移除這個規則，但 PyYAML 的 safe_load 與部分舊版工具仍然以 YAML 1.1 為預設行為。兩字母國家碼、1.0 之類的版本字串、使用者輸入的值——養成加引號的習慣最安全。

陷阱 2：註解會被靜默丟掉

YAML 可以用 # 寫註解，JSON 則不支援。YAML 裡的註解在轉換過程中會被完全丟棄：

# 本機 DB 連線資訊（請勿修改）
host: db.prod.internal
port: 5432  # PostgreSQL 標準 port

轉換結果：

{ "host": "db.prod.internal", "port": 5432 }

不管用什麼轉換器，標準 JSON 裡都放不了 YAML 的註解。如果註解內容是重要資訊，用 ruamel.yaml 單獨抽出，或另存一份文件來管理。JSON 環境中保留註解的替代方法詳見 JSON 註解方式。

陷阱 3：多文件 YAML — 預設只轉第一份

YAML 可以用 --- 分隔符號在一個檔案裡放多份文件：

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

預設行為：

• yaml.safe_load（Python）：不給警告，只回傳第一份
• yaml.load（js-yaml）：同上，只有第一份
• yq -o=json '.'：連續輸出多份 JSON（compact 模式下是合法的 NDJSON）

要把所有文件都拿到、包成一個 JSON 陣列：

yq eval-all '[.]' -o=json multi.yaml

Python：

import yaml, json
docs = list(yaml.safe_load_all(open("multi.yaml")))
json.dump(docs, open("multi.json", "w"), indent=2)

Node.js：

const docs = yaml.loadAll(fs.readFileSync("multi.yaml", "utf8"));
fs.writeFileSync("multi.json", JSON.stringify(docs, null, 2));

Kubernetes manifest 檔案絕大多數是多文件結構，一定要明確處理這個差異。Markdown frontmatter 也是 YAML 文件，轉換時有類似陷阱，詳見 Markdown frontmatter 格式與語法。

陷阱 4：yaml.load 有保安風險，務必用 safe_load

Python PyYAML 的預設 yaml.load 允許建立任意 Python 物件：

!!python/object/apply:os.system ["rm -rf /"]

用 yaml.load 讀入惡意建構的 YAML 檔，系統指令會被執行。處理不受信任的輸入時，務必用 yaml.safe_load（多文件用 yaml.safe_load_all）。

Node.js 的 js-yaml 把舊版的 safeLoad 廢棄、改以 yaml.load 作為預設安全函式，危險的功能則獨立成 unsafeLoad。Python 與 Node 的命名規則是反的，一定要確認。

yq 用的是 Go 的 yaml.v3，沒有對應 Python !!python/object 的功能，所以是安全的。

陷阱 5：整數鍵變成字串

YAML 允許整數型的鍵：

123: first
456: second

JSON 物件的鍵只能是字串，所以轉換時會自動 cast：

{ "123": "first", "456": "second" }

一般來說沒問題，但如果下游應用程式是用整數鍵做 lookup（obj[123]），變成字串鍵（obj["123"]）之後就會找不到。應用層需要檢查並轉回整數。

陷阱 6：錨點與別名（Anchor & Alias）會被 inline 展開

YAML 可以用 &anchor 定義一個值、再用 *alias 引用它：

defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults
  host: prod.internal

staging:
  <<: *defaults
  host: stage.internal

轉成 JSON 後，錨點會被展開——production 與 staging 兩個物件都會拿到完整的預設值副本：

{
  "defaults": { "timeout": 30, "retries": 3 },
  "production": { "timeout": 30, "retries": 3, "host": "prod.internal" },
  "staging": { "timeout": 30, "retries": 3, "host": "stage.internal" }
}

資料本身是正確的，但「這些共用預設值」的原始設計意圖就看不到了。JSON 沒有錨點的概念，所以即使再轉回 YAML，原本的錨點結構也不會恢復。

陷阱 7：1.0 變成浮點數（版本字串被破壞）

YAML 會自動把看起来像數值的值解析為數字型別：

version: 1.0
release: 2026

轉換結果：

{ "version": 1.0, "release": 2026 }

如果你想要的是字串 "1.0"（版本標籤），它會被強制轉成浮點數 1.0，然後依 JSON encoder 的不同，輸出成 1 或 1.0。if version == "1.0" 這種字串比較邏輯就會失敗。

解法：版本號加引號，明確指定為字串：

version: "1.0"
release: "2026"

手機號、郵遞區號（"01234" 前面的 0 會消失）、看起來像十六進位的 commit hash（"e10" 會被誤認成 1e+10 指數記法）也都是同樣的問題。

陷阱 8：型別推斷行為因 schema 而異

YAML 規格有 3 種標準型別推斷 schema：

• FailSafe schema：只處理字串、序列、mapping。完全不解析數字與布林值，最嚴格的模式。
• JSON schema：與 JSON 的原生型別（字串、數值、布林值、null、陣列、物件）完全一致。不會發生 Norway 問題，yes/no 也不會被解析成布林值。
• Core schema（YAML 1.2 預設）：在 JSON schema 基礎上擴充，把 null、Null、NULL、~、空值都當作 null；true/false/True/False/TRUE/FALSE 當作布林值。

大多數現代工具以 Core schema 為預設。部分舊版工具仍然以 YAML 1.1 的完整 schema（包含 Norway 問題與 yes/no）為預設。

Python 指定 JSON schema：

yaml.safe_load(text, Loader=yaml.SafeLoader)  # 預設安全模式

Node.js js-yaml 指定：

yaml.load(text, { schema: yaml.JSON_SCHEMA });

yq v4 預設使用 YAML 1.2 Core schema，所以不會發生 Norway 問題。

線上工具比較

2026 年時點，主要線上 YAML 轉 JSON 工具的實際比較：

機密性高的 YAML（Kubernetes Secret、Ansible vault、含 API token 的 CI 設定）處理時，「瀏覽器內處理」這點很關鍵。在 DevTools 的 Network 分頁切成離線模式再操作，工具如果還在動，就代表真的沒有對外連線。FormatArc 在網路斷開的狀態下也能正常運作。

多文件 YAML 的話，上面列的線上工具都只處理第一份。需要完整多文件轉換或 NDJSON 輸出的話，用 yq 或 Python。

YAML 到 JSON Lines（NDJSON）串流處理

輸入是多文件 YAML、輸出要餵給串流消費者（Kafka producer、逐行 DB loader、日誌收集器）時，JSON Lines（NDJSON）格式是最合適的。

用 yq

# NDJSON：每份 YAML 文件轉成一行 JSON
yq -o=json -I=0 '.' multi.yaml

# 過濾後輸出 NDJSON
yq -o=json -I=0 '.items[]' kubernetes-list.yaml

用 Python 串流

import yaml
import json
import sys

for doc in yaml.safe_load_all(sys.stdin):
    sys.stdout.write(json.dumps(doc, ensure_ascii=False) + "\n")

執行方式：python3 yaml2ndjson.py < multi.yaml > multi.ndjson。

不管輸入檔案多大，記憶體用量都是恆定的（O(1)），所以幾千篇文件的大型 YAML 日誌檔也能安全處理。

管線到 Kafka / BigQuery / S3

# 串流載入 BigQuery
yq -o=json -I=0 '.' events.yaml | bq load --source_format=NEWLINE_DELIMITED_JSON dataset.events -

# 串流上傳 AWS S3
yq -o=json -I=0 '.' events.yaml | aws s3 cp - s3://bucket/events.ndjson

# 透過 kafkacat 傳到 Kafka topic
yq -o=json -I=0 '.' events.yaml | kafkacat -P -b broker:9092 -t events

CI/CD 自動化

三個常見管線平台的 YAML 轉 JSON 步驟範例。

GitHub Actions

name: Convert YAML config to JSON
on: [push, pull_request]

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
        run: yq -o=json '.' config.yaml > config.json
      - name: Validate against JSON Schema
        run: |
          npx ajv-cli validate -s schema.json -d config.json

GitLab CI

convert-yaml:
  image: mikefarah/yq:latest
  stage: validate
  script:
    - yq -o=json '.' config.yaml > config.json
    - jq empty config.json   # 最後一次語法檢查
  artifacts:
    paths:
      - config.json

Jenkins（Declarative Pipeline）

pipeline {
  agent any
  stages {
    stage('Convert YAML to JSON') {
      steps {
        sh 'yq -o=json . config.yaml > config.json'
        sh 'jq empty config.json'
      }
    }
  }
}

不管哪個平台，轉換就是一條命令，直接插在管線中間即可。Node.js 環境中也可以用 formatarc npm 在終端機完成轉換。

Kubernetes 實務工作流

實際營運環境中很常見的 pattern：取得正在跑的 Deployment、編輯、YAML 與 JSON 來回切換。

# 以 JSON 取得目前的 Deployment（kubectl 兩種格式都支援）
kubectl get deployment web-app -o json > deployment.json

# 或者用 YAML 取得後再轉（順便驗證本地 yq 有沒有裝好）
kubectl get deployment web-app -o yaml | yq -o=json '.' > deployment.json

# 用 jq 修改（例如調整 replica 數）
jq '.spec.replicas = 5' deployment.json > updated.json

# 為了 commit 到 Git 再轉回 YAML
yq -P '.' updated.json > deployment.yaml

# 套用到叢集
kubectl apply -f deployment.yaml

串成一條管線：

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

這個 pattern 適用於 kubectl 的所有資源、Helm chart values、Custom Resource Definition（CRD）。

常見問題

YAML 的 country: NO 為什麼變成 false？

這就是著名的「Norway 問題」。YAML 1.1 規格把 NO、Off、n、False 這類沒有引號的字串自動解析為布林值 false。解法是加引號：country: "NO"。YAML 1.2 規格已移除這個行為，但很多工具仍預設用 1.1。yq v4 使用 YAML 1.2 Core schema，不會出這個問題。

YAML 的註解能保留到 JSON 輸出嗎？

不能。標準 JSON 規格沒有註解語法。如果註解很重要，用 ruamel.yaml 把註解單獨抽出、或在 JSON 環境中改存 YAML 檔案作為 source of truth。

多文件 YAML 轉換時會怎樣？

大多數工具預設只轉第一份文件。要拿全部：Python 用 yaml.safe_load_all、Node.js 用 yaml.loadAll、或 yq eval-all '[.]' 包成 JSON 陣列。如果要一行一份文件的串流輸出，用 yq -o=json -I=0 產出 NDJSON。

YAML 要轉成 JSON Lines（NDJSON）怎麼辦？

yq -o=json -I=0 '.' multi.yaml 可以產出壓縮的「一行一份文件」格式。Python 則用 yaml.safe_load_all 串流讀入、逐行 json.dumps() 輸出。NDJSON 是 BigQuery、S3、Kafka 等串流消費端的標準格式。

YAML 能轉成 JSON5（允許註解的擴充）嗎？

JSON5 是允許註解的 JSON 超集。要轉成 JSON5，得先轉成標準 JSON 後再手動把註解加回去，或使用自訂工具。json5.org在新分頁中開啟 的參考實作能解析與輸出 JSON5，但主流 YAML 函式庫沒有直接輸出 JSON5 的功能。

錨點與 merge key 在 JSON 中會保留嗎？

不會。JSON 沒有錨點或別名的概念，轉換時會被 inline 展開。資料內容保持正確，但「這些共用預設值」的結構性意圖就消失了。

沒有 yq 或 Python 也能把 YAML 轉 JSON 嗎？

用 FormatArc YAML to JSON 瀏覽器工具 就行，不需安裝、瀏覽器內完成。另外，幾乎所有現代作業系統都內建 Python 3，裝了 pyyaml 之後一列指令也能用。

反向轉換（JSON 轉 YAML）

要把 JSON 轉回 YAML，FormatArc 也提供對向工具。程式端可用 yq -P '.'、yaml.dump、js-yaml 的 yaml.dump、或 Go 的 yaml.Marshal，語法與本文對稱。詳細比較與 Kubernetes、Docker Compose、Ansible 實務見 JSON 轉 YAML 比較。

總結

YAML 轉 JSON 有五種方法，依需求選用：

• 不需安裝、機密資料：FormatArc YAML to JSON — 瀏覽器內完成、附行號的錯誤提示
• CLI 與 DevOps 管線：yq -o=json '.' — 事實標準
• Python 應用：yaml.safe_load（嚴禁 yaml.load）+ json.dump
• Node.js 應用：js-yaml（yaml.load，保安考量指定 JSON schema）
• Go 服務：gopkg.in/yaml.v3 + encoding/json，多文件用 Decoder 迴圈

8 個陷阱（Norway 問題 / 註解遺失 / 多文件處理 / yaml.load 保安風險 / 整數鍵變字串 / 錨點展開 / 1.0 變浮點數 / schema 依歸的型別推斷）幾乎每個人至少會踩一次。守住三個原則——模糊的字串加引號、用 safe_load、多文件明確處理——其餘都是自然衍生出來的。