从 JSON5 到 JSONC：解锁更”宽容”的 JSON 格式化新体验

当严格的 JSON 让你因为缺少一个逗号而调试到深夜时，“更宽容”的替代方案变得必要。让我们来认识 JSON 的两位更友好的”亲戚” — JSON5 和 JSON with Comments (JSONC)。

背景：为什么需要”宽容”JSON？

可读性困境：标准 JSON 不允许注释、尾随逗号、单引号等写法，难以在配置文件和演示中清晰表达开发意图。
团队协作：多人维护大型 JSON 时，无法加注释易导致误解；每次字段调整都可能引发格式错误。
DevOps 场景：Kubernetes、CI/CD 管道常需动态合并和生成配置，更宽松的格式可减少手工修正工作量。

JSON5 与 JSONC 概览

特性	JSON (原生)	JSON5	JSONC
单行 `//` 注释	不支持	支持	支持
多行 `/* */` 注释	不支持	支持	支持
尾随逗号	不支持	支持	支持
单引号字符串	不支持	支持	不支持
无引号键名	不支持	支持	不支持
数字前导 +/-	不支持	支持	不支持
十六进制/二进制数字	不支持	支持	不支持
官方规范维护者	ECMA	社区 (A. Rauschmayer)	Microsoft / VS Code

核心区分：JSON5 更接近 JavaScript 对象字面量，而 JSONC 仅为标准 JSON “加上注释能力”。

语法示例对比

原生 JSON（严格）

{
  "name": "Go Tools",
  "features": ["Base64", "JSON Formatter"]
}

JSON5 示例

// 项目配置
{
  name: 'Go Tools',      // 允许单引号与无引号键名
  features: [
    'Base64',
    'JSON Formatter',    // 尾随逗号
  ],
  version: 1.0,          // 支持非字符串数字键值
}

JSONC 示例

{
  // 项目名称
  "name": "Go Tools",
  // 功能列表
  "features": [
    "Base64",
    "JSON Formatter", // 尾随逗号
  ]
}

格式化与解析支持

场景	JSON5	JSONC	推荐工具 / 库
浏览器	`JSON5.parse()` polyfill、Prettier 内置 json5 parser (>= v1.13)	VS Code settings.json 原生支持	—
Node.js	`json5` npm 包	`comment-json`, `jsonc-parser`	支持 CLI 格式化与 AST 解析
IDE	VS Code、WebStorm 插件	VS Code 原生、WebStorm 插件	Prettier 可统一格式化
CI / Lint	`eslint-plugin-json5`	`eslint-plugin-jsonc`	可与 Husky & lint-staged 集成
在线工具	Go Tools JSON Formatter（支持 JSON5、JSONC 一键美化 & 校验）	同左	JSON 格式化工具

VS Code 一键格式化

在 settings.json 中添加以下配置：

"[jsonc]": {
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

即可使用 Alt+Shift+F 快速美化带注释的 JSONC 文件。

落地实践与注意事项

1. 生产环境前转换

浏览器原生 JSON.parse 依旧只接受严格 JSON。
在构建阶段通过 rollup-plugin-json5 或自定义脚本将 JSON5/JSONC 转成纯 JSON。

2. 安全与可信度

更宽容意味着潜在”隐藏字段”风险；上线前务必进行 Schema 校验。
使用 JSON Schema 或 zod 做数据验证，防止注释字段泄漏到 API 响应。

3. 团队规范

在 README 或贡献指南中明确 *.json5 仅作配置，发布包请使用 .json。
Lint/Prettier 统一规则，避免 PR 因格式差异产生无意义 diff。

4. 性能

解析 JSON5/JSONC 需要额外依赖，影响启动速度。
但通常对 CLI 和开发环境可接受。

结语

在追求可读性与严格性之间找到平衡，是现代前后端协作的经典难题。JSON5 与 JSONC 提供了更友好的书写体验，只要在构建流程与校验机制上补足，就能安全地享受”宽容 JSON”的便利。

从 JSON5 到 JSONC：解锁更宽容的 JSON 格式化体验