YAML 轉 JSON

YAML 轉 JSON 做的事情很具體：先把 YAML 解析成記憶體裡的資料結構，再把這份結構按 JSON 的語法重新寫出來。資料本身沒變，變的只是它的「寫法」。YAML 用縮排、短橫線、註解來表達層級；JSON 用大括號、中括號、帶引號的鍵。轉換是一次重新編碼，不是改造。

為什麼會有這個方向的轉換需求

YAML 是人願意手寫的格式——Kubernetes 清單、CI 流水線、Hugo/Jekyll front matter、OpenAPI 規範；JSON 是機器更願意消費的格式。轉換發生在這兩邊的交界處。

真正容易出問題的，不是大括號，而是 YAML 自己的語義

很多 YAML 看起來像一般文字，但真正決定結構的是縮排、清單標記、布林值、null、引號和特殊語法。像錨點、別名、多行文字這些能力，在轉成一般 JSON 後不一定還能保留原來的書寫意圖。所以更穩妥的做法是：先確認 YAML 本身結構清楚，再把產生出來的 JSON 當作機器側結果去審查。

YAML 轉換前最值得先看的幾個點

如何使用這個工具

1. 先在 YAML 轉 JSON 中准备一份有代表性的需要变成更严格机器可读輸出的 YAML 配置檔案和片段，不要一开始就處理最大或最敏感的真实内容。
2. 执行處理流程并產生可用于結構化審查或下游工具的 JSON 结果后，優先檢查缩进、列表標記、布尔值、null 值，以及 YAML 源内容是否已经规范化，再判断结果是否真的可用。
3. 只有当结果已经適合用于接口准备、配置迁移、結構校验和文档到程式碼的交接，并且不再触发這条风险提醒时，才複製或下载輸出：YAML 里的锚点或少见写法在转成普通 JSON 后可能仍需人工複核。

YAML 轉 JSON 範例

這個 YAML 轉 JSON 示例使用有代表性的需要变成更严格机器可读輸出的 YAML 配置檔案和片段，展示產生后的可用于結構化審查或下游工具的 JSON 结果，便于你先確認缩进、列表標記、布尔值、null 值，以及 YAML 源内容是否已经规范化，再把同样設定用于真实輸入。

範例輸入

service: api
retries: 3
enabled: true

預期輸出

{
  "service": "api",
  "retries": 3,
  "enabled": true
}

一份小型 YAML 設定與對應的 JSON

# YAML
title: Sample
enabled: true
server:
  host: localhost
  port: 8080
features:
  - search
  - export

// JSON
{
  "title": "Sample",
  "enabled": true,
  "server": { "host": "localhost", "port": 8080 },
  "features": ["search", "export"]
}

注意註解和空白行在 JSON 裡都沒了——JSON 本就沒有這些概念。如果某條註解承載了真實資訊，應在轉換前先挪到 description 欄位，不要事後補救。

常見使用場景

YAML 轉 JSON 最適合用在需要变成更严格机器可读輸出的 YAML 配置檔案和片段需要快速变成可用于結構化審查或下游工具的 JSON 结果的場景，尤其是接口准备、配置迁移、結構校验和文档到程式碼的交接。

• 用于把 YAML 转成適合解析器、接口或校验器的 JSON，服务于接口准备、配置迁移、結構校验和文档到程式碼的交接。
• 處理重要輸入前，可先用示例流程確認缩进、列表標記、布尔值、null 值，以及 YAML 源内容是否已经规范化。
• 当结果符合目標流程后，再複製或下载可用于結構化審查或下游工具的 JSON 结果。

YAML 轉 JSON 時容易踩到的邊界

YAML 转 JSON 出意外，多数不是工具错了，而是 YAML 接受了一些 JSON 表达不了或解读不一致的写法。提前知道这些点，审查输出会快得多。

• “挪威问题”：早期 YAML 把不带引号的 no 解析成布尔 false。新解析器修正了这点，但旧链路里国家代码 NO 仍可能被误读。
• 未加引号的版本号如 1.10 会被解析为数字 1.1，尾部 0 丢失。版本号在 YAML 里始终要加引号。
• 锚点和别名（&base / *base）在 JSON 里会展开。结果是对的，但不再共享结构，diff 会突然变大。
• 块级字符串用 | 还是 > 决定换行如何保留：转成 JSON 后都是字符串，但内容不同。
• 部分 YAML 解析器允许重复键；JSON 不允许。冲突时，工具通常静默保留后一个值。

YAML 與 JSON 各自的強項對比

使用注意

• 複用可用于結構化審查或下游工具的 JSON 结果前，先檢查缩进、列表標記、布尔值、null 值，以及 YAML 源内容是否已经规范化。
• YAML 里的锚点或少见写法在转成普通 JSON 后可能仍需人工複核。
• 当结果会影响生产工作或客户可见内容时，應保留原始需要变成更严格机器可读輸出的 YAML 配置檔案和片段以便回退和核对。

YAML 轉 JSON 參考說明

YAML 轉 JSON 的参考說明應始终围绕需要变成更严格机器可读輸出的 YAML 配置檔案和片段、產生的可用于結構化審查或下游工具的 JSON 结果，以及用于接口准备、配置迁移、結構校验和文档到程式碼的交接前必须確認的檢查点。

• 輸入重点：需要变成更严格机器可读輸出的 YAML 配置檔案和片段。
• 輸出重点：可用于結構化審查或下游工具的 JSON 结果。
• 複核重点：缩进、列表標記、布尔值、null 值，以及 YAML 源内容是否已经规范化。

參考資料

• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format
• ECMA-404: The JSON Data Interchange Syntax
• YAML 1.2.2 Specification