# @gerhobbelt/json5 中文文档

规范地址：https://npmcn.com/package/%40gerhobbelt/json5/

版本：2\.1\.0-48
npm 元数据更新时间：2022-04-05T13:58:56.960Z
中文译文更新时间：2026-11-16T05:23:42.883Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gerhobbelt/json5
原文对照：https://npmcn.com/package/%40gerhobbelt/json5/?lang=original
项目主页：http://json5.org/
源码仓库：https://github.com/json5/json5

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：236 kB，14 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=8
- 运行依赖：1 个
- 首次发布：2017-08-27T12:51:21.537Z
- 最新版本发布：2019-09-20T22:24:24.569Z
- 近 30 天下载量：26036（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 0 个）

## 中文简介

JSON为人类服务.

## 安装

```sh
npm install @gerhobbelt/json5
```

也可以使用：`pnpm add @gerhobbelt/json5`、`yarn add @gerhobbelt/json5`、`bun add @gerhobbelt/json5`

## README

# JSON5 – 人类的JSON

[![GitHub Repository](https://img.shields.io/badge/github-json5%2Fjson5-blue.svg)](https://github.com/json5/json5) [![npm version](https://img.shields.io/npm/v/@gerhobbelt/json5.svg)](https://npmjs.com/package/@gerhobbelt/json5) [![Build Status](https://api.travis-ci.org/GerHobbelt/json5.svg)](https://travis-ci.org/GerHobbelt/json5) [![Coverage Status](https://coveralls.io/repos/GerHobbelt/json5/badge.svg?branch=master&service=github)](https://coveralls.io/github/GerHobbelt/json5?branch=master) [![Dependency Status](https://david-dm.org/GerHobbelt/json5.svg)](https://david-dm.org/GerHobbelt/json5)

> # 通知
> 
> 这个寄存器包含由GerHobbelt维护的叉. 最初的JSON5作品有: [json5/json5 (中文(简体) )](https://github.com/json5/json5)。 。 。 .
> 
> 有关所有变化(修正和特征)的概述,见本节 [有新的还是不同的?](https://npmcn.com/package/%40gerhobbelt/json5/#readme-user-content-whats-new-or-different) 还见下文.

JSON5数据交换格式(JSON5)是一个超集 [贾森](https://tools.ietf.org/html/rfc8259) 旨在 通过扩大其语法以包括: 一些作品来自: [ECMAScript 5.1 (中文(简体) )](https://www.ecma-international.org/ecma-262/5.1/)。 。 。 .

这个JavaScript库是JSON5官方引用执行的衍生工具 解析和序列化库,其中此衍生工具包含一些额外的功能: 这些额外项目在下面的特征列表中以 q 来标示.

## 为什么

JSON不是最友好的 _写入_键、对象和 数组不能有后缀逗号, 不允许评论 — 尽管 今天普通JavaScript没有出现这种情况.

JSON的目标是要成为伟大的数据格式 已经扩大 _机器_JSON现在用于写作 [配置](http://plovr.com/docs.html), (中文(简体) ), [清单](https://www.npmjs.org/doc/files/package.json.html)连 [测试](http://code.google.com/p/fuzztester/wiki/JSONFileFormat) - 全部通过 _人类_。 。 。 .

也有其他形式比较人性友好,如YAML,但改变 从JSON到完全不同的形式在许多情况下是不可取的. JSON5的目标是保持与JSON和JavaScript的相近.

## 特征概述

以下ECMAScript 5.1功能在JSON中没有支持,具有 已扩展至JSON5.

### 对象

-   对象密钥可以是 ECMAScript 5.1 _[标识符Name](https://www.ecma-international.org/ecma-262/5.1/#sec-7.6)_。 。 。 .
-   对象可能有一个单一的后导逗号.

### 阵列

-   阵列可能有一个后导逗号.

### 字符串

-   字符串可以单独引用.
-   字符串可以通过逃避新的行字符来跨越多行.
-   字符串可能包括人物出逃.
-   字符串可能是 [ES2015型 “.”多行字符串模板文字](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals)。 。 。 .
-   字符串可能是 ["英雄"弦乐](https://en.wikipedia.org/wiki/Here_document)。 。 。 .

注意下文关于增强字符串格式的章节中提到的限制.

### 数字

-   数字可能是十六进制.
-   数字可能有一个先入后出的小数点.
-   数字可能是 [IEEE 754 (英语)](http://ieeexplore.ieee.org/servlet/opac?punumber=4610933) 阳性无穷,阴性无穷,而纳能.
-   数字可以以明确加号开头.

## RegExp 实例(和衍生类)

-   🎷🍓 [RegExp 类](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) 实例 序列化为至少具有这些属性的正则对象:
    
    -   `re` (单位:千美元)[`=RegExp.toString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/toString)
    -   `source` (单位:千美元)[`=RegExp.source`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/source)(中文(简体) )
    -   `flags` (单位:千美元)[`=RegExp.flags`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/flags)(中文(简体) )
    
    任意 [可浏览属性](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/keys) 新增实例将列入JSON5产出.
    

## 出错实例(和衍生类别)

-   🎷🍓 [错误类](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) 实例 序列化为至少具有这些属性的正则对象:
    
    -   `name` (单位:千美元)[`=Error.name`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/name)
    -   `message` (单位:千美元)[`=Error.message`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/message)(中文(简体) )
    
    任意 [可浏览属性](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/keys) 新增实例将列入JSON5产出.
    

### 评论

-   允许单行和多行评论.

### 空白

-   允许添加白空字符 .

## 简短示例

```js
{
  // comments
  unquoted: 'and you can quote me on that',
  singleQuotes: 'I can use "double quotes" here',
  lineBreaks: "Look, Mom! \
No \\n's!",
  hexadecimal: 0xdecaf,
  leadingDecimalPoint: .8675309, andTrailing: 8675309.,
  positiveSign: +1,
  trailingComma: 'in objects', andIn: ['arrays',],
  "backwardsCompatible": "with JSON",
}
```

## 规格

关于JSON5格式的详细解释,请改为: [正式 规格](https://json5.github.io/json5-spec/)。 。 。 .

## 安装

### 节点.js

```sh
npm install @gerhobbelt/json5
```

```js
const JSON5 = require('@gerhobbelt/json5')
```

### 浏览器

```html
<script src="https://unpkg.com/@gerhobbelt/json5@2.1.0-48"></script>
```

这将建立一个全球 `JSON5` 变量.

## API 密码

JSON5 API 兼容 [JSON API (英语)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON)。 。 。 .

### `JSON5.parse()`

解析 JSON5 字符串,构建 JavaScript 值或由 JavaScript 描述的对象 绳子。 可以提供一种可选的复活器功能来进行 在返回之前先在生成对象上转换.

#### 语法

```
JSON5.parse(text[, reviver])
```

#### 参数

-   `text`:要解析为JSON5的字符串.
    
-   `reviver`: 如果一个函数, 则该函数将规定由 解析是转换的,在返回之前.
    
    `reviver` 调用函数参数 : `(key, value)`时
    
    -   `this`: 引用包含密钥/值对的JavaScript对象.
    -   `key`: 代表属性的字符串 `value`。 。 。 .
    -   `value`: 该数值 `this[key]` 属性,由JSON5解析.
    
    这个 `reviver()` 函数返回函数(可能更改/“活化”) `value`。 。 。 .
    
    何时 `reviver()` 返回时 `undefined`,属性(`this[key]`)为 _删除_ 从对象.
    
    解析出 JSON5 对象树的根也传入 `reviver()` 作为 带有密钥的属性 `''` (空字符串),因此允许 `reviver()` 到后处理 解析出 JSON5 输入的每个部分 .
    
    请注意: `reviver()` 作为JSON5 分析的一部分 _后处理_ 从而 当遇到重复密钥时, 无法用于编码交替行为 输入对象或其他解析错误: JSON5 首先进行全解析, 在 引用 `reviver()` 在每一个再生成的元素上.
    

#### 返回值

对应给定的JSON5文本的对象.

### `JSON5.stringify()`

将 JavaScript 值转换为 JSON5 字符串,如果是 指定替换器函数,或可选择仅包括指定的 如果指定了替换器阵列,则属性.

#### 语法

```
JSON5.stringify(value[, replacer[, space[, circularRefHandler]]])
JSON5.stringify(value[, options])
```

#### 参数

-   `value`: 转换为 JSON5 字符串的值.
    
-   `replacer`: 改变字符串化行为的函数 进程,或用作白名单的字符串和数字对象数组 用于选择/过滤要包含的值对象的属性 jSON5弦乐 如果该值无效或不提供,则该值的所有属性 对象包含在产生的 JSON5 字符串中.
    
-   `space`: 用于将空白插入到 为可读性目的输出 JSON5 字符串。 如果这是一个数字,它 表示要用作白空格的空格字符数; 此数字是 上限为10(如果大于10,则数值仅为10)。 数值小于1 表示不应使用空格。 如果这是字符串,则字符串(或 字符串的前10个字符,如果更长)作为白色使用 空间。 如果未提供此参数( 或为无效) , 则不使用空白 . 如果使用白色空间,在对象和阵列中会使用后缀逗号.
    
-   `circularRefHandler`: QQ 为每个元素引用的回调函数 否则会造成 `JSON5.stringify()` 丢出一个 `"converting circular structure to JSON5"` _类型错误_ 除外.
    
    回调返回取而代之的字符串值 。 当此值 恰好包含循环引用本身,然后会被检测到 以 `JSON5.stringify()` 编码为 `'[!circular ref inside circularRefHandler!]'` 取而代之的是字符串值.
    
    回调函数参数 : `(value, circusPos, stack, keyStack, key, err)`时
    
    -   `value`: 循环参考值.
    -   `circusPos`编号: `stack[]` 财务报告和审定财务报表 `keyStack[]` 数组,表示 引用的父对象 `value` 循环参考值.
    -   `stack`: 用于此值的家长堆栈(对象,阵列)。 第一个条目 (指数 0) 是根 `value`。数组是一个快照(shallow clone),以确保 用户代码可以简单地直接存储此引用值 [不冒险 JSON5 - 内部关闭问题,在我们不提供时会产生 带快照的你](https://stackoverflow.com/questions/750486/javascript-closure-inside-loops-simple-practical-example)。 。 。 .
    -   '键盘' : 用于描述路径的密钥堆栈, 每个父键一个 根的违法循环参考值 `value` 下来。 第一个条目 (指数 0) 是根 `value`。当您想要显示诊断时有用 它在根值中列出通过对象等级的正向路径 参考文件 `value` 例如,在手边.  
        阵列是快照( shallow clone) 以确保 用户代码可以简单地直接存储此引用值 [不冒险 JSON5 - 内部关闭问题,在我们不提供时会产生 带快照的你](https://stackoverflow.com/questions/750486/javascript-closure-inside-loops-simple-practical-example)。 。 。 .
    -   `key`: 当前直接父密钥 `value`。与 `keyStack[keyStack.length - 1]`。 。 。 .
    -   `err`: 类型错误 `JSON5.stringify()`:在这里提供,所以你 用户定义的回调码可以舍弃以丢弃循环引用错误 无论如何.
-   `options`: 具有下列属性的对象:
    
    -   `replacer`: 与 `replacer` 参数.
    -   `space`: 与 `space` 参数.
    -   `quote`: 表示序列化时要使用的引用字符串 字符串。 在未明确指明的情况下,JSON5将用弹性方式确定 每个字符串值的引用以最小化字符数 逃出(从而将输出大小最小化).
    -   `circularRefHandler`: QQ 为每个元素引用的回调函数 否则会造成 `JSON5.stringify()` 丢出一个 `"converting circular structure to JSON5"` _类型错误_ 除外。 见 `circularRefHandler` 关于更多信息的上述参数描述.
    -   `noES6StringOutput`: qq 当设定为 `true` (或有真实价值) `JSON5.stringify()` 将不会输出 (''''''') backtick-encoded ES6 字符串字符串; 相反, 字符串将用 JSON5 标准输出 单引出或双引出字符串值。 您可以设置此选项为 输出将与其他标准 JSON5 阅读器相容的 JSON5 文件 .

#### 返回值

代表值的 JSON5 字符串 .

### 节点.js `require()` JSON5 文件

当使用Node.js时,你可以 `require()` JSON5 通过添加以下文件 语句.

```js
require('json5/lib/register')
```

然后,你可以加载 JSON5 文件与节点.js `require()` 语句。 对于 示例:

```js
const config = require('./config.json5')
```

**页:1**这当然是假设 `require`d JSON5 文件不包含“ heredoc” 格式化 字符串内容 !

## 国 际

由于JSON比JSON5被更广泛使用,此包包括用于 将 JSON5 转换为 JSON5 并用于验证 JSON5 文档的语法.

### 安装

```sh
npm install --global @gerhobbelt/json5
```

### 使用量

```sh
json5 [options] <file>
```

若为 `<file>` 不提供,则使用STDIN.

#### 选项 :

-   `-s`, (中文(简体) ), `--space`: 缩进或缩进的空格数 `t` 标签
-   `-o`, (中文(简体) ), `--out-file [file]`: 输出到指定文件, 否则为 STDOUT 。 (如果 `-` 以 `file` 名称,使用STOUT。 )
-   `-v`, (中文(简体) ), `--validate`: 验证 JSON5 但不输出 JSON
-   `-V`, (中文(简体) ), `--version`: 输出版本编号
-   `-h`, (中文(简体) ), `--help`: 产出使用信息

## 捐款

### 发展

```sh
git clone https://github.com/GerHobbelt/json5
cd json5
npm install
```

输入代码时, 请写相关的测试并运行 `npm test` 财务报告和审定财务报表 `npm run lint` 在提交拉动请求之前。 请使用支持的编辑器 [编辑器配置](http://editorconfig.org/)。 。 。 .

### 问题

报告错误或请求JSON5数据格式的特性,请 将问题提交 [正式规格 仓库](https://github.com/json5/json5-spec)。 。 。 .

报告错误或请求 JavaScript 执行的特性 JSON5 请向这个寄存器提交一个问题.

## 贡献者

[巨头](http://github.com/GerHobbelt/json5/contributors)

## \-什么是新的还是不同的?

以下是一份综合清单,列出与《公约》相比的特征和修正 [原文](https://github.com/json5/json5)

-   增加了对 [ES2015型 “.”多行字符串模板文字](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals),比如说.
    
    ```
    { str: `multiline
            example
            string value!` 
    }
    ```
    
    **关于此增强字符串格式的注释**数字 :
    
    -   虽然 [模板字面谱](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Template_literals) 否则,我们仍不支持JSON5中的八分子出逃 '`'-delimited *multiline strings*, as these ARE NOT identical to JavaScript 'template strings' as we DO NOT intend to support the` ${...} 模板变量扩展功能 !
        
        这个 _多行字符串字符串_ 方便撰写 JSON5 内容 如果字符串内容跨越多行和/或 包含各种引用字符,从而尽可能减少逃避的必要性 内容.
        
    -   任何MAC或WINDOWS风格行端被转换为标准的UNIX行端, 即这些转换由JSON5自动完成:
        
        -   CRLF - > 低频
        -   CR - > 低频
-   增加了对 [异语字符串](https://en.wikipedia.org/wiki/Here_document) 数值, 必须从 `<<` 紧接着有一个标记,例如:. `EOT` 或者说 其它一些字母标识符,当单独在一行中使用时,会 表示“heredoc”字符串的结尾.
    
    例如:
    
    ```
    { str: <<EOT
            multiline EOT
            example \n
            string value!
    EOT
    }
    ```
    
    将字串编码
    
    ```
            multiline EOT
            example \n
            string value!
    ```
    
    即,任何异教内容都不会被视为逃脱! (本节) `\n` 内 因此读取为 JavaScript 字符串 `"\\n"`. ) (中文(简体) )
    
    **关于此增强字符串格式的注释**数字 :
    
    -   解析此语义值时, 我们必须先提取 EOT 标记 还有 一旦我们做了,我们跳过第一行,开始 扫描/ 消耗性异端文献内容, 直到我们点击线路上的 EOT 标记 单靠自己,就是白空间.
        
    -   我们接受两个以上(!) `<` 要标记异端语块开始的字符.
        
    -   我们接受任何非白空字符序列 作为异端EOT标记.
        
    -   根据惯例,我们不接受EOT之前的“格式化白空间/缩进” 标记在同一行.
        
        这个 _内容_ (一) 首个CR/LF之后开始的格言; 我们不会容忍 追随白空间 或任何其他十字架 跟随EOT标记!
        
    -   JSON5扫描一个孤独的异教 EOT 标记以终止字符串内容; 直到我们找到一个, 一切都是字串的内容.
        
    -   文中的内容 DOES NOT 处理出局序列 : 一切都以-is方式传递 !
        
    -   内容 ENDS _在此之前_ 单 EOT 标记之前的最后一个 CR/LF; 即 EOT 标记必须存在 在一条线本身, 没有任何前行或后行的白色空间.
        
    -   如果JSON5字段后面是更多的数据,则分隔符(comma,括号, 必须存在于线上 _过去_ eOT 标记行: EOT 必须是 里面有明显的"孤"字,例如:
        
        ```
        { str: <<EOT
        multiline EOT
        example \n
        string value!
        EOT
        , extra: 42
        }
        ```
        
    -   CR / CRLF / LF MAC / Windows/UNIX行在内容中结尾为"不转换".
        
        这不同于上述“多线字符串字元”类型, 中,所有行尾自动转换为 UNIX 样式 “\\n”. 因此,人们可以认为,本文献是: _二进制数据_ 格式.
        
-   🎷🍓 `JSON5.stringify()` 带着一个 _第四届_ 参数:可选的回调方法 中每个值将被引用的字符串 a “周期性引用”错误另投.
    
    用户指定的调用可以提供替代值来代为编码 或最终丢弃错误例外.
    
    另见上文API文件.
    
-   QQ 复制对象中相同的密钥, 在解析 JSON5 输入时引起语法错误 . (例如,当您提供手动编辑的 JSON5 内容时,就可能发生这种情况) 改为 `JSON5.parse()` 或处理 JSON5 内容时( 不正确) 由任意文本 diff/ patch 工具合并. )
    

## 许可证

麻省理工学院. 见 [利比里亚](https://github.com/json5/json5/blob/master/LICENSE.md) 页:1 细节.

## 贷项

[刺杀基肖尔](https://github.com/aseemk) 创建了这个项目.

[迈克尔·博林](http://bolinfest.com/) 独立抵达并公布 这些想法中有一些 有着惊人的解释和细节。 建议 读取 : [建议改进JSON](http://bolinfest.com/essays/json.html)

[道格拉斯克罗克福德](http://www.crockford.com/) 设计并建造 JSON 但他的状态机器图上 [JSON网站](http://json.org/),作为 虽然听起来很俗气,但给了我们动力和信心,让我们相信建立一个新的 执行这些想法的策略已经可以实现! 原画 jSON5的应用也直接从道格的开源软件中模拟出来 [json parse.js](https://github.com/douglascrockford/JSON-js/blob/master/json_parse.js) par. 我们感谢那个干净和有记录的 代码.

[马克思·纳纳西](https://github.com/MaxNanasy) 已经是一个早期和丰富的 支持者,贡献多块补丁和想法.

[安德鲁·艾森伯格](https://github.com/aeisenberg) 提供原件 `stringify` 方法.

[约旦 塔克](https://github.com/jordanbtucker) jSON5 已更紧密地对齐 与ES5,写了JSON5的官方规格, 完全重写了 正在积极维护这个项目.

## 相关材料

讨论试图解决同一问题的材料包和文件 或非常类似的问题:

机器可读(和-可写)结构数据 这对人类来说是容易的 _读取_ 财务报告和审定财务报表 _写入_。 。 。 .

### 软件包

-   贾森: [http://hjson.org/ (中文(简体) )](http://hjson.org/) 编号 : [https://github.com/hjson/hjson (英语)](https://github.com/hjson/hjson)
-   JSONext: (英语) [https://github.com/jordanbtucker/jsonext 页面存档备份,存于互联网档案馆](https://github.com/jordanbtucker/jsonext)
-   贾森: [https://github.com/kof/node-cjson (英语)](https://github.com/kof/node-cjson)

### 文档

-   [https://github.com/json5/json5/issues/190 页面存档备份,存于互联网档案馆](https://github.com/json5/json5/issues/190) 编号 : [https://github.com/hjson/hjson/issues/87 (中文(简体) )](https://github.com/hjson/hjson/issues/87)

## 常见问题

### @gerhobbelt/json5 是什么？

JSON为人类服务\.

### 如何安装 @gerhobbelt/json5？

在项目目录运行 npm install @gerhobbelt/json5，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 json5，可以用 npx json5 直接运行。

### @gerhobbelt/json5 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/gerhobbelt\_\_json5 是否存在。

### @gerhobbelt/json5 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @gerhobbelt/json5 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=8。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @gerhobbelt/json5 可以商用吗？

@gerhobbelt/json5 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gerhobbelt/json5 的下载量有多少？

根据 npm 官方下载统计，@gerhobbelt/json5 在 2026/10/16 – 2026/11/14 这 30 天内被下载 26,036 次，日均约 868 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gerhobbelt/json5 还在维护吗？

最新版本 2\.1\.0-48 发布于 2019/09/21（7 年前）；至今共发布 28 个版本，其中过去 12 个月发布了 0 个；首次发布于 2017/08/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

