JSON vs YAML vs TOML：你应该用哪种配置格式？

JSON、YAML 和 TOML 是软件开发中最流行的三种配置格式。每种格式都有各自的优势和取舍。本指南提供全面的对比分析，帮助你为项目选择合适的格式。

使用我们的免费工具在 JSON 和 YAML 之间即时转换 →

各格式概述

JSON（JavaScript 对象表示法）

JSON 由 Douglas Crockford 在 2000 年代初期提出，是一种源自 JavaScript 对象字面量语法的轻量级数据交换格式。其设计目标是简洁：用最少的规则使任何编程语言都能轻松解析。如今它是 Web API、配置文件（如 package.json 和 tsconfig.json）以及数据存储的事实标准。

YAML（YAML Ain't Markup Language）

YAML 于 2001 年由 Clark Evans、Ingy döt Net 和 Oren Ben-Kiki 首次提出。最初名为"Yet Another Markup Language"，后更名以体现其面向数据（而非文档）的本质。YAML 为人类可读性而设计，广泛用于 DevOps 工具，如 Docker Compose、Kubernetes 清单、Ansible Playbook 以及 CI/CD 配置（GitHub Actions、GitLab CI）。

TOML（Tom 的明显最小化语言）

TOML 由 Tom Preston-Werner（GitHub 联合创始人）于 2013 年创建，专门作为一种最小化且无歧义的配置格式。其目标是语义明显、易于阅读，能清晰地映射到哈希表。TOML 是 Rust（Cargo.toml）、Python（pyproject.toml）和 Hugo 静态网站的标准配置格式。

语法对比

下面用三种格式表达相同的配置：

JSON

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "debug": true
  },
  "database": {
    "host": "db.example.com",
    "port": 5432,
    "name": "myapp",
    "credentials": {
      "username": "admin",
      "password": "secret"
    }
  },
  "features": ["auth", "logging", "cache"],
  "max_connections": 100
}

YAML

# Server configuration
server:
  host: localhost
  port: 8080
  debug: true

# Database settings
database:
  host: db.example.com
  port: 5432
  name: myapp
  credentials:
    username: admin
    password: secret

features:
  - auth
  - logging
  - cache

max_connections: 100

TOML

# Server configuration
max_connections = 100
features = ["auth", "logging", "cache"]

[server]
host = "localhost"
port = 8080
debug = true

[database]
host = "db.example.com"
port = 5432
name = "myapp"

[database.credentials]
username = "admin"
password = "secret"

功能对比

何时使用各格式

使用 JSON 的场景

// Typical JSON use cases
// package.json
{
  "name": "my-app",
  "version": "1.0.0",
  "scripts": {
    "dev": "next dev",
    "build": "next build"
  }
}

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "strict": true
  }
}

使用 YAML 的场景

# Docker Compose
services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html

# GitHub Actions
name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

使用 TOML 的场景

# Cargo.toml (Rust)
[package]
name = "my-app"
version = "0.1.0"
edition = "2021"

[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

# pyproject.toml (Python)
[project]
name = "my-package"
version = "1.0.0"
requires-python = ">=3.9"

[tool.ruff]
line-length = 88
target-version = "py39"

常见陷阱

YAML：缩进问题

YAML 使用缩进定义结构。混用制表符和空格，或缩进层级不一致，是 YAML 最常见的错误来源。

# BAD: mixing tabs and spaces (invisible but breaks YAML)
services:
	web:          # tab character - YAML error!
    image: nginx

# BAD: inconsistent indentation
services:
  web:
      image: nginx   # 4 spaces here
    ports:            # 2 spaces here - error!
      - "80:80"

# GOOD: consistent 2-space indentation
services:
  web:
    image: nginx
    ports:
      - "80:80"

YAML："挪威问题"

在 YAML 1.1 中，未加引号的 NO、yes、on、off 会被解释为布尔值。国家代码"NO"（挪威）会变成 false。这已导致了实际的 Bug。YAML 1.2 修复了这一问题，但很多解析器仍默认使用 1.1 的行为。

# The "Norway Problem" - YAML 1.1
countries:
  - name: Norway
    code: NO          # Parsed as boolean false!
  - name: Sweden
    code: SE          # Parsed as string "SE"
  - name: Finland
    code: FI          # Parsed as string "FI"

# Other surprising boolean values in YAML 1.1:
truthy:  yes          # boolean true
falsy:   no           # boolean false
enabled: on           # boolean true
disabled: off         # boolean false
positive: TRUE        # boolean true
negative: False       # boolean false

# FIX: Always quote values that could be misinterpreted
countries:
  - name: Norway
    code: "NO"        # Now correctly a string
  - name: Sweden
    code: "SE"
settings:
  enabled: "yes"      # Now correctly a string

JSON：尾随逗号

JSON 不允许尾随逗号。在数组或对象的最后一个元素后加逗号会导致解析错误。这是手动编辑 JSON 文件时最常见的错误之一。

// BAD: trailing comma after last element
{
  "name": "my-app",
  "version": "1.0.0",
  "private": true,    // <-- trailing comma = PARSE ERROR
}

// BAD: trailing comma in array
{
  "colors": [
    "red",
    "green",
    "blue",            // <-- trailing comma = PARSE ERROR
  ]
}

// GOOD: no trailing commas
{
  "name": "my-app",
  "version": "1.0.0",
  "private": true
}

TOML：嵌套表语法

TOML 中的深层嵌套结构可能变得冗长。每一层都需要自己的 [section.subsection] 头部，对于复杂层级关系来说不如 JSON 或 YAML 的嵌套直观。

# TOML: deeply nested config can be verbose
[server]
host = "localhost"

[server.ssl]
enabled = true

[server.ssl.certificates]
cert = "/path/to/cert.pem"
key = "/path/to/key.pem"

[server.ssl.certificates.ca]
bundle = "/path/to/ca-bundle.pem"

# The same in YAML is more compact:
# server:
#   host: localhost
#   ssl:
#     enabled: true
#     certificates:
#       cert: /path/to/cert.pem
#       key: /path/to/key.pem
#       ca:
#         bundle: /path/to/ca-bundle.pem

# TOML inline tables can help for shallow nesting:
[server]
host = "localhost"
ssl = { enabled = true, cert = "/path/to/cert.pem" }

转换工具

需要在格式之间切换？使用我们的免费在线转换器：

JSON ↔ YAML 转换器——支持双向转换和格式化选项

TOML ↔ YAML 转换器——在 TOML 和 YAML 之间即时转换

使用我们的免费工具在 JSON 和 YAML 之间即时转换 →

使用我们的免费工具在 TOML 和 YAML 之间即时转换 →