JSON5 教程

JSON5 是 JSON 的扩展格式，目标是更易手写和维护（例如配置文件）。
合法 JSON 文件始终是合法 JSON5；JSON5 在 JSON 语法上增加了 ECMAScript 5.1 的部分特性。官方站点：json5.org。在线验证可使用本站工具：JSON5 解析验证。

一、JSON5 与 JSON 的关系

JSON5 ⊃ JSON：标准 JSON 可直接作为 JSON5 解析。
面向人类：适合 config、本地设置；机器间通信仍推荐 strict JSON。
与 ES5 的关系：JSON5 值语法是 ES5 的子集（字符串中 U+2028/U+2029 等细节见规范）。

二、相对 JSON 新增的特性

2.1 对象（Object）

键名可以是 IdentifierName（不必加双引号），如 name: 'Cron'
允许单个尾随逗号：{ a: 1, }

2.2 数组（Array）

允许单个尾随逗号：[1, 2, ]

2.3 字符串（String）

可用单引号：'hello'
可用反斜杠续行（行尾 \ 后换行）
支持常见转义序列（与 JSON/JS 类似）

2.4 数字（Number）

十六进制：0xdecaf
可写前导或尾随小数点：.5、8675309.
支持 +Infinity、-Infinity、NaN
可写显式正号：+1

2.5 注释（Comments）

单行：// comment
多行：/* comment */

2.6 空白字符（White Space）

除 JSON 允许的空白外，JSON5 还允许更多 Unicode 空白字符作为分隔（详见规范）。

2.7 重复 key（Duplicate Keys）

与 JavaScript 的 JSON.parse、本站使用的官方 json5 库一致： 同一 object 内若出现相同 key，不会报错，后面的值会覆盖前面的值（保留最后一次出现）。标准 JSON 规范不允许重复 key，但多数解析器也是这种「后者覆盖」行为。

只影响同一层级的 object；不同层级的同名 key 互不影响。
无引号 key 与带引号同名 key 视为同一个键，例如 a: 1 与 "a": 2 仍算重复。
配置文件中应避免故意写重复 key，否则容易掩盖错误。

{
  a: 1,
  a: 2,
  b: 3,
  a: 4
}

// JSON5.parse 后等价于：
// { "a": 4, "b": 3 }

三、综合示例

打开 JSON5 解析验证，点击加载示例可载入带中文注释的综合示例；再点解析验证查看结构化结果，或转标准 JSON得到 strict JSON。示例覆盖：无引号键名、单引号、续行、十六进制与特殊数值、尾随逗号、单行/多行注释、重复 key 等。

/* JSON5 综合示例 — 完整版请在工具中「加载示例」 */
{
  // 无引号 key
  appName: 'Cron专业工具',
  "version": "1.0.0",          // 与 JSON 兼容

  intro: "Cron 提供 \
JSON 校验、JSON5 解析 \
等在线工具",                   // 反斜杠续行

  featureFlags: 0xdecaf,       // 十六进制
  metrics: { ratio: +.8675309, count: 8675309., delta: +1 },
  limits: { maxRetries: +Infinity, minScore: -Infinity, unknown: NaN },

  tools: ['JSON校验', 'JSON排序', 'JSON5解析验证',],  // 数组尾随逗号

  duplicateKeyDemo: {
    status: 'draft',
    status: 'active',          // 重复 key → 后者覆盖，最终为 'active'
  },

  note: '详见工具内完整注释示例',
}

四、常用 API（JavaScript）

npm 包 json5 的 API 与 JSON 类似：

方法	说明
`JSON5.parse(text[, reviver])`	将 JSON5 字符串解析为 JavaScript 值
`JSON5.stringify(value[, replacer[, space]])`	将 JavaScript 值序列化为 JSON5 字符串

npm install json5

const JSON5 = require('json5')
const obj = JSON5.parse("{ unquoted: 'yes', // comment\n}")
const text = JSON5.stringify(obj, null, 2)

五、CLI 验证

官方 CLI 可只做语法校验（不输出 JSON）：

npm install --global json5
json5 -v config.json5    # 仅验证，不输出

本站 JSON5 解析验证提供类似的在线校验与预览。

六、使用建议

配置文件、前端构建配置（如部分工具链）适合 JSON5。
REST API、日志落库、跨语言协议请使用标准 JSON。
解析通过后可用「转标准 JSON」得到 strict JSON 再交给只认 JSON 的系统。
避免在同一 object 中重复定义相同 key，以免静默覆盖导致排查困难。