从 JSON5 到 JSONC：解锁更「宽容」的 JSON 格式化新体验
当严格的 JSON 让你因为缺少一个逗号而调试到深夜时，「更宽容」的替代方案变得必要。让我们来认识 JSON 的两位更友好的「亲戚」 — JSON5 和 JSON with Comments (JSONC)。
什么是 JSON5？
JSON5 是 JSON 的扩展，融合了 ECMAScript 5.1 的特性，包括无引号键名、尾逗号、单引号字符串、注释和十六进制数字。它由社区维护，旨在让手写配置文件比严格 JSON 更易读、更宽容。
什么是 JSONC？
JSONC（JSON with Comments）是标准 JSON 的最小扩展，增加了单行（//）和多行（/* */）注释支持以及尾逗号。由 Microsoft 维护，是 VS Code 设置文件、tsconfig.json 等 TypeScript 配置文件的原生格式。
背景：为什么需要「宽容」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 有什么区别？
JSON5 使用类似 JavaScript 的语法扩展了 JSON：支持无引号键名、尾随逗号、单行和块注释、十六进制数字以及多行字符串。JSONC 更简单——仅在标准 JSON 基础上添加了单行（//）和块（/* */）注释。如果只需要注释功能，选择 JSONC；如果需要更丰富的语法，选择 JSON5。
JSON5 或 JSONC 可以用于生产环境 API 吗？
不建议——JSON5 和 JSONC 是为配置文件设计的，不适合数据交换。API 应使用标准 JSON（RFC 8259）以确保最大互操作性。将 JSON5/JSONC 保留给 tsconfig.json、.vscode/settings.json 等本地配置文件，这些场景下人类可读性比机器解析更重要。
VS Code 原生支持 JSON5 吗？
VS Code 原生支持 JSONC（其自身的设置文件就使用 JSONC），但不开箱支持 JSON5。要使用 JSON5，需要从 VS Code 扩展市场安装专用扩展（如”JSON5 syntax”）。你也可以在设置中将 .json5 文件关联到 JSON5 语言模式。
如何将 JSON5 转换为标准 JSON？
使用 json5 npm 包：JSON5.parse() 读取 JSON5，然后用 JSON.stringify() 输出标准 JSON。命令行用法：运行 npx json5 < input.json5 > output.json。在线工具（如我们的 JSON 格式化工具）也可以验证转换后的输出以确保正确性。
JSONC 就是 JSON with Comments 吗？
是的——JSONC 全称为”JSON with Comments”，是 VS Code、TypeScript（tsconfig.json）和其他 Microsoft 工具使用的格式。它遵循标准 JSON 规范，唯一的扩展是支持 // 和 /* */ 注释。解析器在处理前会剥离注释，因此生成的数据结构与标准 JSON 完全相同。
如需更多浏览器端开发者工具，包括 Base64 编码、哈希生成和时间戳转换，请参阅我们的开发者工具必备指南。
结语
在追求可读性与严格性之间找到平衡，是现代前后端协作的经典难题。JSON5 与 JSONC 提供了更友好的书写体验，只要在构建流程与校验机制上补足，就能安全地享受「宽容 JSON」的便利。