JSON 配置文件：严格、通用的结构化格式

JSON 是一种轻量、文本化、与编程语言无关的数据交换格式。它能直接表示对象、数组和常见基础类型，因此非常适合由程序生成、跨语言传递，或与应用内部数据结构一一映射的配置。

JSON 的优势来自严格和克制：语法规则少、解析器普遍、结果较少歧义。代价是标准 JSON 不支持注释，也不接受尾逗号、单引号和未加引号的键。人工频繁维护时，这些限制会变得明显。

一、完整示例

{
  "app": {
    "name": "config-demo",
    "debug": false,
    "features": ["search", "cache"]
  },
  "server": {
    "host": "127.0.0.1",
    "port": 8080
  },
  "database": {
    "pool_size": 10
  }
}

对象用花括号表示，数组用方括号表示。这里的 false、8080 和 10 分别是布尔值与数字，不是字符串；读取后通常可以直接映射到对应语言的基础类型。

二、常用语法

JSON 只有六类值：

对象：{"name": "config-demo"}，由字符串键和任意 JSON 值组成。
数组：["search", "cache"]，元素有顺序，也可以继续嵌套对象或数组。
字符串：必须使用双引号；换行、双引号和反斜杠需要转义。
数字：支持整数、小数和指数形式，但不支持 NaN 或无穷大。
布尔值：只能写小写的 true 或 false。
空值：写作 null。

对象成员和数组元素之间使用逗号，键和值之间使用冒号。最后一项后面不能留下逗号：

{
  "port": 8080,
  "debug": false
}

下面这些写法不是标准 JSON：

{ port: 8080 }          # 键没有双引号
{ "port": 8080, }       # 尾逗号
{ "debug": False }      # 布尔值大小写错误
{ 'name': 'demo' }      # 使用单引号

三、适用场景

JSON 适合以下情况：

配置由程序生成、更新或通过网络接口下发。
多种语言和工具都需要读取同一份文件。
数据天然由对象和数组组成，而且不依赖文件内注释。
项目已有 JSON Schema 或其他校验流程。
配置同时会作为测试夹具、缓存内容或数据交换样本使用。

如果最终用户需要长期手工维护大量说明文字，或配置中存在很多重复结构，YAML、TOML 甚至 XML 可能更合适。

四、与其他格式对比

对比格式	JSON 的优势	JSON 的不足
YAML	语法更严格，缩进和隐式类型造成的歧义更少	没有注释，多层对象的括号和引号更多
TOML	更适合机器交换，几乎所有语言都有成熟实现	不像 TOML 那样专门面向人工维护的配置
XML	文本更短，映射到常见对象和数组更直接	缺少命名空间、元素与属性之分及内建 Schema 生态
INI	原生支持数组、布尔值、数字和深层对象	写简单键值时没有 INI 直观

JSON 与 JavaScript 对象字面量相似，但两者不能混用。JavaScript 允许的注释、函数、undefined、单引号和部分宽松写法，都不属于 JSON。

五、常见错误与安全提醒

不要依赖重复键。规范建议对象中的名称唯一；解析器面对重复键时可能报错，也可能只保留其中一个值。
注意数字精度。JSON 没有限定统一的整数位数，接收端可能把大整数转换为浮点数而丢失精度。标识符和超大整数必要时应使用字符串。
不要用 eval 解析。应使用真正的 JSON 解析器，避免把输入当作可执行代码。
限制资源消耗。面对外部输入时，应限制文件大小、嵌套深度和字符串长度。
区分缺失与 null。某个键不存在和键存在但值为 null，在配置语义上可能完全不同。
校验业务字段。语法正确只代表它是合法 JSON，不代表端口范围、必填字段或字段拼写正确。

六、选型建议

当配置主要由机器处理、需要跨语言互通，且注释不是刚需时，JSON 是稳妥的默认选择。若文件主要由人维护并需要解释复杂选项，可比较 TOML 或 YAML；若仍想保留 JSON 生态，可以额外维护独立说明文档或使用 JSON Schema 描述约束，而不要私自发明“带注释的 JSON”却仍命名为 .json。

七、官方资料

上一篇：常用配置文件总览与选型指南
下一篇：INI 配置文件：简洁的分节键值格式