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

从 JSON5 到 JSONC：更”宽容”的 JSON 规范及其格式化支持

當严格的 JSON 让你因为 缺少一个逗号 而 debug 到深夜，或许是时候了解更“宽容”的替代方案 —— JSON5 和 JSON with Comments (JSONC)。

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

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

2. JSON5 与 JSONC 概览

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

一句话区分：JSON5 更像 JavaScript 对象字面量，而 JSONC 只是给标准 JSON 加上注释能力。

3. 语法示例对比

3.1 原生 JSON（严格）

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

3.2 JSON5 示例

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

3.3 JSONC 示例

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

4. 格式化与解析支持

场景	JSON5	JSONC	推荐工具 / 库
浏览器	JSON5.parse() polyfill prettier w/ built‑in json5 parser (≥ Prettier v1.13)	VS Code settings.json 原生支持	Chrome DevTools 尚不支持直读
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 一键美化 & 严格校验)	同左	https://go-tools.org/json-formatter

VS Code 一键格式化

在 settings.json 中添加：

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

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

5. 落地实践与注意事项

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 & Dev 环境可接受。

6. 结语

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

🎉 试一试：访问 Go Tools JSON Formatter → 贴入你的 JSON5/JSONC 代码 → 即时格式化 & 语法高亮，助你秒杀丑 JSON！

---

参考链接

• JSON5 官方仓库: https://github.com/json5/json5
• JSONC 语法说明 (VS Code): https://github.com/microsoft/node-jsonc-parser
• Prettier parser docs (JSON5, JSONC): https://prettier.io/docs/options#parser
• comment-json: https://github.com/kaelzhang/node-comment-json

---