JSONC 是什么？

JSONC（JSON with Comments）是 JSON 的一个扩展格式，允许在 JSON 数据中添加注释。这个规范由 jsonc.org 定义，旨在形式化一种在实践中广泛使用但缺乏正式标准的格式。

起源与背景

JSONC 格式最初由微软非正式地引入，用于 VS Code 的配置文件，包括：

settings.json - 编辑器设置
launch.json - 调试配置
tasks.json - 任务配置

伴随着这种非正式格式，微软发布了一个公开可用的解析器 jsonc-parser。JSONC 规范的目标是将 JSONC 格式形式化，定义 jsonc-parser 在默认配置下认为有效的内容。

语法规则

JSONC 遵循与 JSON 相同的语法规则，并额外支持 JavaScript 风格的注释。

单行注释

单行注释以 // 开始，延伸到行尾：

{
  // 这是单行注释
  "name": "John Doe",
  "age": 30
}

多行注释

多行注释以 /* 开始，以 */ 结束，可以跨越多行：

{
  /*
   * 这是多行注释
   * 可以跨越多行
   */
  "name": "Jane Doe",
  "age": 25
}

尾随逗号

JSONC 解析器可以支持尾随逗号（Trailing Commas），但并非强制要求。

尾随逗号指出现在数组最后一个元素或对象最后一个属性后的逗号：

{
  "items": [
    "apple",
    "banana",
    "orange",  // ← 这是尾随逗号
  ],
}

为什么尾随逗号不是必需的？

根据规范，尾随逗号不是必需的，原因如下：

参考实现 jsonc-parser 默认情况下不允许尾随逗号
allowTrailingComma 选项默认为 false，任何尾随逗号都会导致解析错误
未来当尾随逗号在 JavaScript 生态系统中得到足够普及时，可能会将其纳入规范

VS Code 中的尾随逗号

VS Code 的 “JSON with Comments” 模式曾默认允许尾随逗号，但后来发生了变化：

现在仍然接受尾随逗号，但会显示警告
例外：VS Code 官方配置文件不会显示警告（因为它们的 JSON Schema 显式允许尾随逗号）

文件扩展名

JSONC 文档的推荐文件扩展名是 .jsonc。

如果使用 .json 扩展名，建议在文件开头添加模式行（Mode Line）来指示这是一个 JSONC 文件：

// -*- mode: jsonc -*-
{
  "name": "example"
}

或者：

// -*- jsonc -*-
{
  "name": "example"
}

主要用途

JSONC 主要适用于以下场景：

配置文件

JSONC 非常适合配置文件，因为注释可以提供解释或说明：

{
  // 服务器监听端口
  "port": 8080,
  
  /* 数据库连接配置
   * 生产环境请修改这些值
   */
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myapp"
  }
}

数据标注

JSONC 允许开发者用注释标注 JSON 数据，以便更好地理解和维护：

{
  "users": [
    {
      "id": 1,
      "name": "Alice",
      // TODO: 需要验证邮箱格式
      "email": "alice@example.com"
    }
  ]
}

语义

JSONC 中的注释在解析时会被忽略，允许开发者标注 JSON 数据而不影响其结构或内容。

工具和库支持

以下是支持 JSONC 的部分工具和库：

语言/平台	库
JavaScript/TypeScript	`microsoft/node-jsonc-parser`
C++	`stephenberry/glaze`
Elixir	`massivefermion/jsonc`
Go	`tidwall/jsonc`
Python	`n-takumasa/json-with-comments`
PHP	`otar/jsonc`
Rust	`dprint/jsonc-parser`
Java	Jackson (`JsonFactory.enable(JsonReadFeature.ALLOW_JAVA_COMMENTS)`)
Kotlin	`kotlinx.serialization.json`

JSON vs JSONC 对比

特性	JSON	JSONC
单行注释	❌	✅
多行注释	❌	✅
尾随逗号	❌	可选支持
标准化	RFC 8259	jsonc.org
典型用途	数据交换	配置文件

JSONC - 带注释的 JSON