JSON5 详细说明-马育民老师

# 介绍

JSON5 是 JSON 的**超集扩展**，完全兼容标准 JSON，核心目标是让**手写配置文件更友好、易维护**，语法借鉴 ES5 规则，适合人工编辑而非机器通信。

- **全称**：JSON5 – JSON for Humans
- **本质**：JSON 超集 + ES5 子集；**合法 JSON 都是合法 JSON5**，合法 JSON5 都是合法 ES5
- **用途**：主打**配置文件**（如项目配置、环境变量），不推荐用于机器间数据交换
- **生态**：Node.js 生态广泛采用（如 Babel、Next.js），鸿蒙、Apple 平台原生支持

### 应用场景

- 项目配置文件（如 `babel.config.json5`、`app.json5`，鸿蒙应用开发配置文件）
- 环境变量配置
- 手写、需频繁修改的配置
- 需要注释说明的配置

# JSON vs JSON5 关键差异

| 特性 | 标准 JSON | JSON5 |
|---|---|---|
| 注释 | ❌ 不支持 | ✅ 单行 `//`、多行 `/* */` |
| 对象键 | 必须双引号 | 可无引号（合法标识符）、单/双引号 |
| 字符串 | 仅双引号、不可换行 | 单/双引号、反斜杠换行 |
| 尾随逗号 | ❌ 禁止 | ✅ 对象/数组末尾允许 |
| 数值 | 仅十进制 | 十六进制 `0xFF`、`+3.14`、`.5`、`5.`、`Infinity`、`NaN` |
| 空白 | 严格限制 | 支持更多空白字符 |

---

# JSON5 完整语法特性
### 1. 注释支持（最实用）
```json5
{
  // 单行注释：说明字段用途
  name: "JSON5",

/*
    多行注释：
    临时禁用区块
  */
  version: "1.0.0"
}
```

### 2. 对象键灵活
- 无引号（合法标识符：字母/`$`/`_` 开头，后续字母/数字/`$`/`_`）
- 单引号/双引号
```json5
{
  normalKey: "无引号",
  'special-key': "单引号",
  "double-key": "双引号"
}
```

### 3. 字符串增强
- 单引号/双引号
- 反斜杠换行（多行字符串）
- 支持转义（`\n`/`\t`/`\\`）
```json5
{
  single: '单引号字符串',
  double: "双引号字符串",
  multi: "第一行\
第二行\
第三行"
}
```

### 4. 数值扩展
- 十六进制：`0xFF`（255）
- 显式正号：`+3.14`
- 首尾小数点：`.5`、`5.`
- 特殊值：`Infinity`、`-Infinity`、`NaN`
```json5
{
  hex: 0xFF,
  positive: +42,
  leadingDot: .5,
  trailingDot: 5.,
  inf: Infinity,
  nan: NaN
}
```

### 5. 尾随逗号（减少错误）
对象/数组最后一个元素后可加逗号，新增元素无需改逗号
```json5
{
  list: [
    "apple",
    "banana", // 尾随逗号合法
  ],
  config: {
    a: 1,
    b: 2, // 尾随逗号合法
  }
}
```

### 6. 宽松空白
支持空格、制表符、换行等，格式更自由

---

# JSON5 示例（完整配置）
```json5
{
  // 应用基础配置
  appName: "MyApp",
  version: "2.0.0",
  isDebug: true,

/* 服务器配置
     包含主机、端口、超时 */
  server: {
    host: "localhost",
    port: 8080,
    timeout: 3000,
  },

// 特性开关
  features: {
    auth: true,
    cache: false,
  },

// 数值示例
  maxRetries: 5,
  pi: 3.14159,
  hexColor: 0x1A2B3C,

// 多行文本
  description: "这是一个\
多行描述文本\
支持换行",
}
```

---

# 使用方式（Node.js）
### 1. 安装
```bash
npm install json5
```

### 2. 解析 JSON5
```javascript
const JSON5 = require('json5');
const fs = require('fs');

// 读取并解析
const raw = fs.readFileSync('config.json5', 'utf8');
const config = JSON5.parse(raw);
console.log(config);
```

### 3. 字符串化
```javascript
const obj = { name: "JSON5", version: "1.0.0" };
const json5Str = JSON5.stringify(obj, null, 2);
console.log(json5Str);
```

---

# 注意事项

### ❌ 不推荐场景
- API 数据交换（标准 JSON 更通用）
- 跨语言数据传输
- 性能敏感的大规模数据解析

### ⚠️ 注意
- 非官方标准，部分语言解析库支持有限
- 浏览器原生不支持，需引入解析库
- 避免在 JSON5 中使用过复杂逻辑，保持配置简洁

---

# 总结
JSON5 是**人性化的 JSON 扩展**，通过**注释、无引号键、单引号字符串、尾随逗号、数值扩展**等特性，大幅提升手写配置的体验。它**完全兼容 JSON**，是 Node.js 生态与配置场景的优选，但不适合机器间通信。

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