JSONC 详细说明

作者：马育民 • • 阅读：10053

介绍

JSONC（JSON with Comments） 是标准 JSON 的最小超集扩展，核心是为 JSON 加入注释支持，同时完全兼容标准 JSON 语法，任何合法 JSON 都是合法 JSONC。由微软主导推广，广泛用于 VS Code、TypeScript 等工具的配置文件。

定义

  • 全称：JSON with Comments（带注释的 JSON）
  • 定位：JSON 的严格超集，仅扩展注释能力，不改动原生语法规则。
  • 设计初衷：解决标准 JSON 不支持注释、配置文件难维护的问题。

起源与流行

  • 由微软为 VS Code 设计，用于 settings.json、launch.json 等配置文件。
  • 2017 年后随 VS Code 普及，成为前端/TypeScript 生态事实标准（如 tsconfig.json）。
  • 官方解析库：微软开源 jsonc-parser，用于解析 JSONC 并剥离注释。

语法规则

兼容 JSON + 注释

1. 完全保留 JSON 原生语法

  • 键必须用双引号（"）包裹，不支持单引号/无引号键。
  • 字符串用双引号，数字/布尔/null 无引号。
  • 不支持尾逗号（数组/对象最后一项后不能加逗号）。
  • 结构严格：对象 {}、数组 []、键值对 key: value。

2. 新增：两种注释（C 风格）

单行注释 //

从 // 开始到行尾，支持行内或独立行。

{
  "name": "JSONC", // 单行注释：名称
  "version": "1.0"
}

多行注释 / /

跨越多行，可包裹代码块，支持行内。

{
  /* 多行注释：
     描述 JSONC 核心特性
  */
  "features": ["comments", "json-compatible"]
}

3. 语法禁忌（与 JSON 一致）

  • ❌ 单引号键/值：{'key': 'val'}
  • ❌ 无引号键：{key: "val"}
  • ❌ 尾逗号：{"a": 1,}
  • ❌ 特殊字符未转义：{"msg": "hello "world""}

JSONC vs 标准 JSON vs JSON5

核心差异对比

特性 标准 JSON JSONC JSON5
注释 ❌ ✅ // /* */ ✅ // /* */
双引号键 ✅ ✅ ✅
无引号键 ❌ ❌ ✅
单引号字符串 ❌ ❌ ✅
尾逗号 ❌ ❌ ✅
兼容性 所有解析器 VS Code/TS 原生 部分工具支持
适用场景 数据交换 配置文件 宽松配置
  • JSONC：极简扩展，只加注释，严格兼容 JSON，适合需注释的配置文件。
  • JSON5：扩展更多（无引号键、单引号、尾逗号），更宽松，但兼容性稍差。

使用场景

1. VS Code 配置（最主流）

  • settings.json：编辑器全局设置
  • launch.json：调试配置
  • tasks.json：任务配置
  • extensions.json：扩展推荐

2. TypeScript 生态

  • tsconfig.json：TypeScript 编译配置（原生 JSONC）。
  • jsconfig.json：JavaScript 项目配置。

3. 其他工具

  • Node.js 项目配置（部分工具支持）
  • 前端构建工具（如 Webpack 配置可通过插件支持）
  • 内部工具配置文件（需注释说明）

解析与转换

1. 原生支持

  • VS Code：内置 JSONC 解析器，直接编辑无压力。
  • TypeScript：tsconfig.json 原生解析 JSONC。

2. 代码解析（剥离注释）

Node.js（jsonc-parser）

npm install jsonc-parser

const jsonc = require('jsonc-parser');
const fs = require('fs');

const content = fs.readFileSync('tsconfig.json', 'utf8');
const errors = [];
const json = jsonc.parse(content, errors); // 解析为标准 JSON 对象
console.log(json);

其他语言

  • Go：github.com/fpatron/jsonc
  • Python：json5 库（兼容 JSONC）
  • Java：com.fasterxml.jackson.core:jackson-databind 配合插件

3. 转换为标准 JSON

  • 工具：VS Code 插件（如“JSON to JSONC”）、在线转换工具。
  • 命令行：
    # 使用 json5 库转换
npx json5 input.jsonc > output.json

优缺点

优点

  1. 可读性强：注释说明配置意图，降低维护成本。
  2. 完全兼容 JSON：标准 JSON 可直接作为 JSONC 使用。
  3. 生态成熟：VS Code/TS 原生支持，工具链完善。
  4. 轻量无冗余：仅扩展注释，不引入复杂语法。

缺点

  1. 非官方标准：未纳入 RFC，依赖工具支持。
  2. 标准解析器不兼容：浏览器 JSON.parse()、后端原生 JSON 库无法直接解析，需先剥离注释。
  3. 功能有限：相比 JSON5，无无引号键、尾逗号等扩展。

使用建议

  1. 配置文件优先用 JSONC：VS Code/TS 项目直接用 .json（VS Code 自动识别 JSONC）。
  2. 注释规范：
    • 单行注释：说明单行配置，用 //。
    • 多行注释：说明代码块/复杂配置，用 /* */。
    • 避免冗余注释：只解释“为什么”，不重复“是什么”。
  3. 构建时剥离注释：生产环境前用 jsonc-parser 或 json5 转换为标准 JSON。
  4. 团队统一规范：约定 JSONC 语法禁忌，避免混用 JSON5 特性。

总结

JSONC 是带注释的标准 JSON，极简扩展、兼容性强、生态成熟，是配置文件的理想选择。它不改变 JSON 核心结构，仅加入注释能力，完美平衡可读性与兼容性。

原文出处：/show_1GW3KnZGXtIf.html

吉ICP备15003043号