JSON 与 YAML 互转完全指南：算法实现、边界处理与生产实践

在现代开发工具链中，JSON 和 YAML 是使用频率最高的两种数据序列化格式。根据 Stack Overflow 2025 年开发者调查，超过 78% 的开发者在日常工作中同时使用这两种格式——JSON 用于 API 通信和数据存储，YAML 用于配置文件和基础设施定义。然而，这两种格式之间的转换并非简单的语法替换：YAML 支持锚点引用（Anchor & Alias）、多文档流（Multi-Document Stream）、注释保留等 JSON 不具备的特性，直接进行格式转换会丢失关键信息甚至引入安全漏洞。

🔍 一、JSON 与 YAML 的核心差异

在动手写转换代码之前，必须理解两种格式在语义层面的根本差异。很多人以为 YAML 只是"人类可读的 JSON"，这是一个危险的误解。

📊 语法与语义对比

⚠️ **警告：**YAML 1.1 中 1e3、.inf、yes、no、on、off 等值会被解析为非字符串类型。如果你的配置文件中包含这些值，转换后可能产生意想不到的结果。

🔐 安全陷阱：YAML 的隐式类型解析

这是大多数开发者忽略的问题。看下面的例子：

# YAML 1.1 中这些值的解析结果
version: 1.0        # → number 1.0 ✅
enabled: yes         # → boolean true（不是字符串 "yes"）
port: 0x1F92         # → number 8082（十六进制）
payload: !!binary SGVsbG8=  # → Binary 类型
response: 200        # → number 200（不是字符串 "200"）

如果服务端期望 enabled 是字符串 "yes" 而不是布尔值 true，直接转换会导致 API 调用失败。更严重的是，恶意构造的 YAML 可以通过 !!python/object 等标签执行任意代码：

# ❌ 危险：YAML 反序列化攻击向量
payload: !!python/object/apply:os.system ["rm -rf /"]

📌 **记住：**在生产环境中进行 YAML 解析时，必须禁用未知标签（!!python/object 等），使用安全模式（Safe Load）。js-yaml 的 load() 函数默认是安全的，但 PyYAML 的 yaml.load() 默认不安全。

🛠️ 二、双向转换的 TypeScript 实现

理解了差异之后，我们来实现一个生产级的 JSON-YAML 双向转换器。核心挑战在于：JSON→YAML 要生成人类可读的输出，YAML→JSON 要处理所有边界情况。

✅ JSON 转 YAML：生成可读输出

JSON 转 YAML 的核心算法是一个递归的序列化过程。关键决策包括：缩进策略、字符串引号选择、多行字符串处理。

// json-to-yaml.ts — JSON 转 YAML 核心实现
interface ToYamlOptions {
  indent?: number           // 缩进空格数，默认 2
  lineWidth?: number        // 行宽限制，默认 80
  noRefs?: boolean          // 是否禁用锚点引用，默认 true
  sortKeys?: boolean        // 是否排序键，默认 false
  quotingType?: '"' | "'"   // 引号类型，默认双引号
  forceQuotes?: boolean     // 是否强制所有字符串加引号
}

function jsonToYaml(data: unknown, options: ToYamlOptions = {}): string {
  const { indent = 2, lineWidth = 80, sortKeys = false } = options

  function serialize(value: unknown, currentIndent: number): string {
    if (value === null || value === undefined) return 'null'
    if (typeof value === 'boolean') return value ? 'true' : 'false'
    if (typeof value === 'number') return serializeNumber(value)
    if (typeof value === 'string') return serializeString(value, currentIndent)
    if (Array.isArray(value)) return serializeArray(value, currentIndent)
    if (typeof value === 'object') return serializeObject(value as Record<string, unknown>, currentIndent)
    return String(value)
  }

  function serializeNumber(num: number): string {
    // 处理特殊数值
    if (Number.isNaN(num)) return '.nan'
    if (num === Infinity) return '.inf'
    if (num === -Infinity) return '-.inf'
    // 整数不带小数点
    if (Number.isInteger(num)) return String(num)
    return String(num)
  }

  function serializeString(str: string, currentIndent: number): string {
    // 空字符串需要引号
    if (str === '') return '""'
    // 需要引号的特殊值
    const needsQuote = /^[\d.eE+-]/.test(str) ||
      /^(true|false|null|yes|no|on|off|~)$/i.test(str) ||
      /^[{[\],&*?|>!%@`]/.test(str) ||
      /[:#\-?]/.test(str) ||
      str.includes('\n')
    if (needsQuote) return `"${str.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n')}"`
    return str
  }

  function serializeArray(arr: unknown[], currentIndent: number): string {
    if (arr.length === 0) return '[]'
    const indentStr = ' '.repeat(currentIndent)
    const items = arr.map(item => {
      const serialized = serialize(item, currentIndent + indent)
      if (typeof item === 'object' && item !== null) {
        return `\n${indentStr}- ${serialized.trimStart()}`
      }
      return `\n${indentStr}- ${serialized}`
    })
    return items.join('')
  }

  function serializeObject(obj: Record<string, unknown>, currentIndent: number): string {
    const keys = sortKeys ? Object.keys(obj).sort() : Object.keys(obj)
    if (keys.length === 0) return '{}'
    const indentStr = ' '.repeat(currentIndent)
    const entries = keys.map(key => {
      const value = obj[key]
      const serialized = serialize(value, currentIndent + indent)
      if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
        return `\n${indentStr}${serializeString(key, currentIndent)}:\n${' '.repeat(currentIndent + indent)}${serialized.trimStart()}`
      }
      return `\n${indentStr}${serializeString(key, currentIndent)}: ${serialized}`
    })
    return entries.join('')
  }

  return serialize(data, 0).trimStart() + '\n'
}

✅ YAML 转 JSON：安全解析与类型归一化

YAML 转 JSON 的难点在于处理 YAML 特有的类型系统。我们需要一个安全的解析器，同时将 YAML 的原生类型映射到 JSON 的有限类型集合。

// yaml-to-json.ts — YAML 转 JSON 核心实现
import * as yaml from 'js-yaml'

interface FromYamlOptions {
  schema?: 'core' | 'default' | 'failsafe' | 'json'  // YAML Schema
  jsonCompat?: boolean     // JSON 兼容模式，只保留 JSON 类型
  keepStrings?: boolean    // 保持字符串不自动转换类型
  maxDepth?: number        // 最大嵌套深度，防止栈溢出
}

function yamlToJson(yamlStr: string, options: FromYamlOptions = {}): unknown {
  const { schema = 'default', maxDepth = 64 } = options

  // 选择 Schema
  const schemaMap = {
    core: yaml.CORE_SCHEMA,
    default: yaml.DEFAULT_SCHEMA,
    failsafe: yaml.FAILSAFE_SCHEMA,
    json: yaml.JSON_SCHEMA,
  }

  // 安全解析配置
  const result = yaml.load(yamlStr, {
    schema: schemaMap[schema],
    onWarning: (warning) => console.warn('YAML Warning:', warning.message),
  })

  // 深度检查防止栈溢出
  function checkDepth(value: unknown, depth: number): void {
    if (depth > maxDepth) throw new Error(`YAML nested depth exceeds ${maxDepth}`)
    if (Array.isArray(value)) value.forEach(item => checkDepth(item, depth + 1))
    if (value && typeof value === 'object') {
      Object.values(value).forEach(v => checkDepth(v, depth + 1))
    }
  }

  checkDepth(result, 0)

  // 归一化：将非 JSON 类型转为 JSON 兼容类型
  function normalize(value: unknown): unknown {
    if (value === null || value === undefined) return null
    if (typeof value === 'boolean' || typeof value === 'number') return value
    if (typeof value === 'string') return value
    if (value instanceof Date) return value.toISOString()
    if (value instanceof Uint8Array) return Buffer.from(value).toString('base64')
    if (Array.isArray(value)) return value.map(normalize)
    if (typeof value === 'object') {
      const result: Record<string, unknown> = {}
      for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
        result[String(key)] = normalize(val)
      }
      return result
    }
    return String(value)
  }

  return normalize(result)
}

// 多文档 YAML 支持
function yamlMultiDocToJson(yamlStr: string, options: FromYamlOptions = {}): unknown[] {
  const results: unknown[] = []
  yaml.loadAll(yamlStr, (doc) => {
    results.push(doc)
  })
  return results.map(doc => {
    function normalize(value: unknown): unknown {
      if (value === null || value === undefined) return null
      if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') return value
      if (value instanceof Date) return value.toISOString()
      if (Array.isArray(value)) return value.map(normalize)
      if (typeof value === 'object') {
        const result: Record<string, unknown> = {}
        for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
          result[String(key)] = normalize(val)
        }
        return result
      }
      return String(value)
    }
    return normalize(doc)
  })
}

💡 **提示：**在生产环境中，建议使用 failsafe Schema（只识别字符串、列表、映射三种类型）来避免隐式类型转换带来的问题。如果需要严格的 JSON 兼容性，使用 json Schema。

⚡ 处理锚点引用（Anchor & Alias）

YAML 的锚点引用是转换中最棘手的部分。js-yaml 默认会自动展开引用，但如果你需要检测或保留引用关系，需要自定义处理：

// anchor-aware-converter.ts — 带锚点感知的转换器
import * as yaml from 'js-yaml'

interface AnchorInfo {
  path: string
  anchor: string
  value: unknown
}

function yamlToJsonWithAnchors(yamlStr: string): {
  data: unknown
  anchors: AnchorInfo[]
  duplicateValues: Map<string, string[]>
} {
  const anchors: AnchorInfo[] = []
  const valuePaths = new Map<string, string[]>()  // 值的 JSON 路径列表

  // 第一遍：解析并收集锚点信息
  const data = yaml.load(yamlStr, {
    // js-yaml 内部会处理锚点展开
  })

  // 第二遍：遍历结果，检测重复值（可能来自锚点引用）
  function findDuplicateValues(value: unknown, path: string = '$'): void {
    if (value === null || value === undefined) return
    if (typeof value === 'object') {
      const jsonKey = JSON.stringify(value)
      const existing = valuePaths.get(jsonKey) || []
      existing.push(path)
      valuePaths.set(jsonKey, existing)
      if (Array.isArray(value)) {
        value.forEach((item, i) => findDuplicateValues(item, `${path}[${i}]`))
      } else {
        for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
          findDuplicateValues(val, `${path}.${key}`)
        }
      }
    }
  }

  findDuplicateValues(data)

  // 找出有多处引用的值
  const duplicateValues = new Map<string, string[]>()
  for (const [jsonKey, paths] of valuePaths.entries()) {
    if (paths.length > 1 && jsonKey.length > 2) {  // 过滤掉简单的原始值
      duplicateValues.set(jsonKey, paths)
    }
  }

  return { data, anchors, duplicateValues }
}

// 使用示例
const yamlWithAnchors = `
defaults: &defaults
  adapter: postgres
  host: localhost
  port: 5432

development:
  <<: *defaults
  database: myapp_dev

production:
  <<: *defaults
  database: myapp_prod
  host: prod-db.example.com
`

const result = yamlToJsonWithAnchors(yamlWithAnchors)
console.log(JSON.stringify(result.data, null, 2))
// 输出中 development 和 production 都会展开 defaults 的值

🚀 三、生产环境实战与性能对比

理论实现只是第一步，在生产环境中还需要考虑性能、错误处理和与现有工具链的集成。

📈 库性能对比基准测试

我们在 Node.js 22 环境下对主流 YAML 库进行了基准测试，测试数据为一个包含 1000 个键值对的嵌套对象：

⚡ **关键结论：**js-yaml 在纯解析速度上表现最佳，而 yaml 库（YAML 官方实现）在 TypeScript 类型支持和 YAML 1.2 规范兼容性上更优。如果你需要 YAML 1.2 严格模式（消除了 yes/no 被解析为布尔值的问题），选择 yaml 库。

🔧 Next.js API 路由中的配置转换服务

在实际项目中，JSON-YAML 转换最常见的场景是配置管理。以下是一个完整的 API 服务实现：

// app/api/convert/route.ts — Next.js 15 配置转换 API
import { NextRequest, NextResponse } from 'next/server'
import * as yaml from 'js-yaml'

export async function POST(request: NextRequest) {
  try {
    const body = await request.json()
    const { source, format, options = {} } = body

    // 参数校验
    if (!source || !format) {
      return NextResponse.json(
        { error: '缺少必要参数：source 和 format' },
        { status: 400 }
      )
    }

    if (format !== 'json-to-yaml' && format !== 'yaml-to-json') {
      return NextResponse.json(
        { error: 'format 必须为 json-to-yaml 或 yaml-to-json' },
        { status: 400 }
      )
    }

    // 限制输入大小（防止 DoS）
    const MAX_SIZE = 1024 * 1024  // 1MB
    if (source.length > MAX_SIZE) {
      return NextResponse.json(
        { error: `输入超过 ${MAX_SIZE / 1024 / 1024}MB 限制` },
        { status: 413 }
      )
    }

    let result: string
    const startTime = performance.now()

    if (format === 'json-to-yaml') {
      const parsed = JSON.parse(source)  // 验证 JSON 合法性
      result = yaml.dump(parsed, {
        indent: options.indent || 2,
        lineWidth: options.lineWidth || 80,
        noRefs: options.noRefs ?? true,
        sortKeys: options.sortKeys ?? false,
        quotingType: options.quotingType || '"',
        forceQuotes: options.forceQuotes ?? false,
      })
    } else {
      const parsed = yaml.load(source, {
        schema: options.strict ? yaml.JSON_SCHEMA : yaml.DEFAULT_SCHEMA,
      })
      result = JSON.stringify(parsed, null, options.indent || 2)
    }

    const duration = performance.now() - startTime

    return NextResponse.json({
      result,
      meta: {
        format,
        inputSize: source.length,
        outputSize: result.length,
        durationMs: Math.round(duration * 100) / 100,
      },
    })
  } catch (error: any) {
    const message = error.message || '转换失败'
    return NextResponse.json(
      { error: message, line: error.mark?.line },
      { status: 422 }
    )
  }
}

⚠️ 生产环境避坑指南

在生产环境中使用 JSON-YAML 转换，以下几个坑点值得特别注意：

❌ 坑点 1：YAML 整数键被转为字符串

# YAML 中数字键是合法的
users:
  1001: alice
  1002: bob

转换为 JSON 后，键会变成字符串 {"1001": "alice"}，因为 JSON 规范要求对象键必须是字符串。如果后端期望数字键，需要额外处理。

❌ 坑点 2：YAML 的 << 合并键

defaults: &defaults
  timeout: 30
  retries: 3

service:
  <<: *defaults
  timeout: 60  # 覆盖 defaults 中的值

<< 是 YAML 的特殊合并键，js-yaml 会正确展开，但某些库（如 yamljs）可能不支持。转换后需要验证输出是否符合预期。

❌ 坑点 3：大文件的内存问题

// ❌ 错误：一次性读取整个大文件
const content = fs.readFileSync('huge-config.yaml', 'utf-8')
const data = yaml.load(content)

// ✅ 正确：使用流式处理
import { createReadStream } from 'fs'
import { createInterface } from 'readline'

async function streamYamlToJson(filePath: string): Promise<unknown[]> {
  const results: unknown[] = []
  let currentDoc = ''
  const rl = createInterface({ input: createReadStream(filePath) })

  for await (const line of rl) {
    if (line === '---') {
      if (currentDoc) {
        results.push(yaml.load(currentDoc))
      }
      currentDoc = ''
    } else {
      currentDoc += line + '\n'
    }
  }
  if (currentDoc) results.push(yaml.load(currentDoc))
  return results
}

⚠️ **警告：**对于超过 10MB 的 YAML 文件，务必使用流式解析。js-yaml 的 load() 会将整个文件解析到内存中，大文件可能导致 V8 堆溢出（JavaScript heap out of memory）。

🏗️ 四、实际应用场景

JSON-YAML 转换不是为了转换而转换，它解决的是真实的工程问题。

🎯 Kubernetes 配置管理

Kubernetes 原生使用 YAML 定义资源，但自动化工具链通常生成 JSON。以下是一个将 JSON 格式的 Deployment 配置转为 Kubernetes YAML 的完整示例：

// k8s-config-generator.ts — K8s 配置生成器
import * as yaml from 'js-yaml'

interface K8sDeployment {
  apiVersion: string
  kind: string
  metadata: { name: string; namespace: string; labels: Record<string, string> }
  spec: {
    replicas: number
    selector: { matchLabels: Record<string, string> }
    template: {
      metadata: { labels: Record<string, string> }
      spec: {
        containers: Array<{
          name: string
          image: string
          ports: Array<{ containerPort: number }>
          env?: Array<{ name: string; value: string }>
          resources?: { limits: Record<string, string>; requests: Record<string, string> }
        }>
      }
    }
  }
}

function generateK8sYaml(config: K8sDeployment): string {
  return yaml.dump(config, {
    indent: 2,
    lineWidth: 120,
    noRefs: true,
    sortKeys: false,
  })
}

// 使用示例
const deployment: K8sDeployment = {
  apiVersion: 'apps/v1',
  kind: 'Deployment',
  metadata: {
    name: 'api-server',
    namespace: 'production',
    labels: { app: 'api-server', version: 'v2.1.0' },
  },
  spec: {
    replicas: 3,
    selector: { matchLabels: { app: 'api-server' } },
    template: {
      metadata: { labels: { app: 'api-server', version: 'v2.1.0' } },
      spec: {
        containers: [{
          name: 'api-server',
          image: 'registry.example.com/api-server:v2.1.0',
          ports: [{ containerPort: 8080 }],
          env: [
            { name: 'NODE_ENV', value: 'production' },
            { name: 'LOG_LEVEL', value: 'info' },
          ],
          resources: {
            limits: { cpu: '500m', memory: '512Mi' },
            requests: { cpu: '250m', memory: '256Mi' },
          },
        }],
      },
    },
  },
}

console.log(generateK8sYaml(deployment))

🎯 CI/CD 流水线配置转换

GitHub Actions、GitLab CI、CircleCI 等平台都使用 YAML 定义流水线。当需要从 JSON 格式的模板批量生成配置时：

// cicd-generator.ts — CI/CD 配置批量生成
import * as yaml from 'js-yaml'

interface GitHubAction {
  name: string
  on: Record<string, unknown>
  jobs: Record<string, {
    'runs-on': string
    steps: Array<{
      uses?: string
      run?: string
      name?: string
      with?: Record<string, string>
      env?: Record<string, string>
    }>
  }>
}

function generateGitHubActions(template: GitHubAction): string {
  return yaml.dump(template, {
    indent: 2,
    lineWidth: 120,
    noRefs: true,
    forceQuotes: false,
  })
}

// 从 JSON 模板生成多环境配置
const environments = ['staging', 'production']
const baseTemplate: GitHubAction = {
  name: 'Deploy',
  on: { push: { branches: ['main'] } },
  jobs: {
    deploy: {
      'runs-on': 'ubuntu-latest',
      steps: [
        { uses: 'actions/checkout@v4' },
        { name: 'Setup Node', uses: 'actions/setup-node@v4', with: { 'node-version': '22' } },
        { run: 'npm ci' },
        { run: 'npm run build' },
      ],
    },
  },
}

for (const env of environments) {
  const config = structuredClone(baseTemplate)
  config.name = `Deploy to ${env}`
  config.jobs.deploy.steps.push({
    name: `Deploy to ${env}`,
    run: `npm run deploy -- --env=${env}`,
    env: { DEPLOY_TOKEN: '${{ secrets.DEPLOY_TOKEN }}' },
  })
  console.log(`# deploy-${env}.yml`)
  console.log(generateGitHubActions(config))
}

📋 最佳实践总结

经过上面的分析和实现，这里总结 JSON-YAML 转换的核心最佳实践：

• ✅ 始终使用安全模式解析 YAML — 生产环境中禁用 !!python/object 等危险标签
• ✅ 显式处理 Date 类型 — YAML 的原生 Date 需要转为 ISO 8601 字符串
• ✅ 限制输入大小和嵌套深度 — 防止 DoS 攻击和栈溢出
• ✅ 验证转换后的输出 — YAML→JSON 后重新 JSON.parse 确保结果合法
• ✅ 保留原始 YAML 的锚点信息 — 在调试时记录哪些值来自锚点引用
• ❌ 不要假设 YAML 值的类型 — yes 可能是布尔值，0x1F 可能是数字
• ❌ 不要忽略 YAML 的 << 合并键 — 不同库的支持程度不同
• ❌ 不要一次性处理超大文件 — 使用流式解析

⚡ **关键结论：**JSON-YAML 转换的核心挑战不在于语法层面的映射，而在于语义层面的类型归一化。选择合适的库（推荐 js-yaml 或 yaml），配置安全的解析选项，处理好边界情况，才能在生产环境中安全运行。

🔗 相关工具推荐

如果你需要在线进行 JSON-YAML 转换，以下工具值得一试：

• jsjson.com JSON 工具箱 — 客户端侧处理，数据不上传服务器，保护隐私安全
• js-yaml — Node.js 生态最成熟的 YAML 解析库
• yaml — YAML 1.2 规范的完整实现，TypeScript 支持优秀
• JSON Formatter & Validator — 在线格式转换工具
• yq — 命令行 YAML/JSON/XML 处理工具，适合 CI/CD 环境

JSON 和 YAML 各有其适用场景，理解它们的差异并掌握安全的转换方法，是每个后端和 DevOps 开发者的必备技能。希望本文的实现方案和避坑指南能帮助你在实际项目中做出更好的技术决策。