JSONC 详细说明-马育民老师

# 介绍

**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 风格）
#### 单行注释 //
从 `//` 开始到行尾，支持行内或独立行。
```jsonc
{
  "name": "JSONC", // 单行注释：名称
  "version": "1.0"
}
```

#### 多行注释 /* */
跨越多行，可包裹代码块，支持行内。
```jsonc
{
  /* 多行注释：
     描述 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）
```bash
npm install jsonc-parser
```
```javascript
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”）、在线转换工具。
- 命令行：
```bash
# 使用 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 核心结构，仅加入注释能力，完美平衡可读性与兼容性。

原文出处：http://malaoshi.top/show_1GW3KnZGXtIf.html