# @cldmv/eslint-plugin-jsonv 中文文档

规范地址：https://npmcn.com/package/%40cldmv/eslint-plugin-jsonv/

版本：1\.1\.2
npm 元数据更新时间：2026-11-07T05:10:30.214Z
中文译文更新时间：2026-11-10T00:40:42.027Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40cldmv/eslint-plugin-jsonv
原文对照：https://npmcn.com/package/%40cldmv/eslint-plugin-jsonv/?lang=original
项目主页：https://github.com/CLDMV/jsonv-eslint-plugin-jsonv/#readme
源码仓库：https://github.com/CLDMV/jsonv-eslint-plugin-jsonv

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

- 包体积（解压后）：52.4 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：^20\.19\.0 \|\| ^22\.13\.0 \|\| \>=24
- 运行依赖：2 个
- peer 依赖：eslint ^9\.13\.0 \|\| ^10\.0\.0，@cldmv/jsonv ^1\.1\.0
- 首次发布：2026-01-19T05:24:38.661Z
- 最新版本发布：2026-11-07T05:10:29.845Z
- 近 30 天下载量：8016（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

@ cldmv/jsonv 文件的 ESLint 插件

## 安装

```sh
npm install @cldmv/eslint-plugin-jsonv
```

也可以使用：`pnpm add @cldmv/eslint-plugin-jsonv`、`yarn add @cldmv/eslint-plugin-jsonv`、`bun add @cldmv/eslint-plugin-jsonv`

## README

# @cldmv/eslint-plugin-jsonv (英语)

[![npm version](https://img.shields.io/npm/v/%40cldmv%2Feslint-plugin-jsonv.svg?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837)](https://www.npmjs.com/package/@cldmv/eslint-plugin-jsonv) [![npm downloads](https://img.shields.io/npm/dm/%40cldmv%2Feslint-plugin-jsonv.svg?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837)](https://www.npmjs.com/package/@cldmv/eslint-plugin-jsonv) [![GitHub downloads](https://img.shields.io/github/downloads/CLDMV/jsonv-eslint-plugin-jsonv/total?style=for-the-badge&logo=github&logoColor=white&labelColor=181717)](https://github.com/CLDMV/jsonv-eslint-plugin-jsonv/releases) [![Last commit](https://img.shields.io/github/last-commit/CLDMV/jsonv-eslint-plugin-jsonv?style=for-the-badge&logo=github&logoColor=white&labelColor=181717)](https://github.com/CLDMV/jsonv-eslint-plugin-jsonv/commits) [![npm last update](https://img.shields.io/npm/last-update/%40cldmv%2Feslint-plugin-jsonv?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837)](https://www.npmjs.com/package/@cldmv/eslint-plugin-jsonv)

[![Contributors](https://img.shields.io/github/contributors/CLDMV/jsonv-eslint-plugin-jsonv.svg?style=for-the-badge&logo=github&logoColor=white&labelColor=181717)](https://github.com/CLDMV/jsonv-eslint-plugin-jsonv/graphs/contributors) [![Sponsor shinrai](https://img.shields.io/github/sponsors/shinrai?style=for-the-badge&logo=githubsponsors&logoColor=white&labelColor=EA4AAA&label=Sponsor)](https://github.com/sponsors/shinrai)

用于验证的 ESLint 插件 `.jsonv` 使用 [翻译:](https://github.com/CLDMV/jsonv) par.

## 曰如何是新来

### 最近:v1.1.2(2026年11月)

-   **工具发布, 无插件更改** 现在使用的 vitest 配置 `devCondition()` 从 `@cldmv/configs`,所以测试真的 逆 `src/` 通过 `eslint-plugin-jsonv-dev` 导出条件,并且类型脚本被拆分为 `types:check` 财务报告和审定财务报表 `types:build` (单位:千美元)[92号](https://github.com/CLDMV/jsonv-eslint-plugin-jsonv/pull/92), (中文(简体) ), [94号](https://github.com/CLDMV/jsonv-eslint-plugin-jsonv/pull/94)) (中文(简体) ). 规则、语言或选项不变.
-   [查看全文 v1.1.2 更改日志](https://github.com/CLDMV/jsonv-eslint-plugin-jsonv/blob/master/docs/changelog/v1/v1.1.2.md)

### 最近发布的

-   **v1.1.1 数据** (2026年11月 - ) (中文(简体) ) `engines.node` 返回运行时间范围 `^20.19.0 || ^22.13.0 || >=24`;22.22.0开发层迁至 `devEngines` (单位:千美元)[88号](https://github.com/CLDMV/jsonv-eslint-plugin-jsonv/pull/88)(中文(简体) )[更改日志](https://github.com/CLDMV/jsonv-eslint-plugin-jsonv/blob/master/docs/changelog/v1/v1.1.1.md)(中文(简体) )
-   **页:1** (2026年11月) — 插件已搬入 `src/`,用tsup, 和一个 `require()` 条目和一个 `eslint-plugin-jsonv-dev` 出口条件; `engines.node` 缩小到 `>=22.22.0` (#82,#83) (中文(简体) )[更改日志](https://github.com/CLDMV/jsonv-eslint-plugin-jsonv/blob/master/docs/changelog/v1/v1.1.0.md)(中文(简体) )
-   **页:1** (2026年10月)——仅发展依赖: `eslint` 10.120.0, vitest 5.0.3 和 `@cldmv/vitest-runner` 1.5.3;没有更改插件代码(#59,#60,#62,#64)([更改日志](https://github.com/CLDMV/jsonv-eslint-plugin-jsonv/blob/master/docs/changelog/v1/v1.0.17.md)(中文(简体) )
-   **页:1** (2026年10月) — 标题工具 `@cldmv/fix-headers` 2.2.0和2 `@cldmv/configs` 1.2.4; 没有更改插件代码或运行时间依赖性(# 54, #57)([更改日志](https://github.com/CLDMV/jsonv-eslint-plugin-jsonv/blob/master/docs/changelog/v1/v1.0.16.md)(中文(简体) )

📚 **完整版本历史参见 [文件/更改日志/](https://github.com/CLDMV/jsonv-eslint-plugin-jsonv/tree/master/docs/changelog/) 编辑 [GitHub 发布](https://github.com/CLDMV/jsonv-eslint-plugin-jsonv/releases)。 。 。 .**

## 特征

-   **语法验证**: 使用 jsonv 解析器验证 jsonv 语法
-   **ES2011-2025 支助**:所有JSON5,ES2015,ES2020,ES2021特性支持
-   **内部参考文献**: 验证赤裸的标识符、模板插入、嵌入式属性访问
-   **BigInt 支持**: 验证 BigInt 文字和数字分隔符
-   **准确错误报告**: 分析错误包括行/列信息
-   **可配置解析**:目标ES年,解析模式,严格BigInt和八进制检查,内部参考解析

## 安装

```bash
npm install --save-dev @cldmv/eslint-plugin-jsonv
```

**所需经费:** 节点 `^20.19.0 || ^22.13.0 || >=24` (插件的范围) `@eslint/core` 财务报告和审定财务报表 `@eslint/plugin-kit` 依赖性支持)和ESLint `^9.13.0 || ^10.0.0` (第一次ESLint发布与 `defaultLanguageOptions` 支持插件 `languages`) (中文(简体) ). `require()` 需要该范围已经覆盖的 ^20.19.0 或 ^22.13.0 节点.

开发这个软件包需要节点22.22.0或以后(`devEngines`) (中文(简体) ).

**说明:** 此插件需要 `@cldmv/jsonv` 作为同伴的依赖.

```bash
npm install @cldmv/jsonv
```

## 构建插件

源头住在 `src/`数字 : `src/index.mjs` 是插件,并且 `src/index.cjs` 是普通JS条目。 为了建造它:

```bash
npm install
npm run build
```

这将:

1.  套装 `src/index.mjs` 输入 `dist/index.mjs` 带有 tsup
2.  复制 `src/index.cjs` 不变 `dist/index.cjs`
3.  生成类型定义为 `dist/index.d.mts`

`dist/` 未犯; `npm pack` 财务报告和审定财务报表 `npm publish` 重建这个系统.

### 从源头运行

包裹 `"."` 导出有 `eslint-plugin-jsonv-dev` 标注在 `src/` 改为 `dist/`在一次离职中, `import` 或者说 `require` 联 合 国 `@cldmv/eslint-plugin-jsonv` 负载 `dist/` 除非设定条件:

```bash
node --conditions=eslint-plugin-jsonv-dev app.mjs
# or once per shell
export NODE_OPTIONS=--conditions=eslint-plugin-jsonv-dev
```

测试套房设置条件本身,所以 `npm test` 运行与 `src/`,则 `npm run test:dist` 建造和检查 `dist/`。 。 。 .

## 使用量

### ESLint平面配置 (eslint.config.mjs) (英语)

```javascript
import jsonv from "@cldmv/eslint-plugin-jsonv";

export default [
    {
        files: ["**/*.jsonv"],
        plugins: { jsonv },
        language: "jsonv/jsonv",
        extends: ["jsonv/recommended"]
    }
];
```

### ESLint平面配置(eslint.config.cjs) 互联网档案馆的存檔,存档日期2011-12-21

软件包也有一个通用JS条目,所以一个通用JS配置可以 `require()` 这个. `require()` 返回插件对象本身,与无害环境管理默认导出对象相同。 这需要一个节点js释放与 `require(esm)` 支持(^20.19.0或QQ22.13.0),支持的节点范围已经保证了.

```javascript
const jsonv = require("@cldmv/eslint-plugin-jsonv");

module.exports = [
    {
        files: ["**/*.jsonv"],
        plugins: { jsonv },
        language: "jsonv/jsonv",
        extends: ["jsonv/recommended"]
    }
];
```

### 配置选项

`languageOptions` 交给 `@cldmv/jsonv` 解析器( 均为 `parseWithOptions()`,用于报告错误,以及 `parseToAst()`,它构建了AST规则。 每个选项都是可选的;下面的值是默认值:

```javascript
{
  files: ["**/*.jsonv"],
  plugins: { jsonv },
  language: "jsonv/jsonv",
  languageOptions: {
    year: 2025,                    // Target ES year: which jsonv features are allowed
    mode: "jsonv",                 // Parse mode: "jsonv", "json5" or "json"
    strictBigInt: false,           // true: an unsafe integer needs the `n` suffix
    strictOctal: false,            // true: legacy `0755` octals are errors (use `0o755`)
    allowInternalReferences: true  // false: references are not resolved or checked
  }
}
```

| 选项 | 类型 | 允许的值 | 默认 | 含义 |
| --- | --- | --- | --- | --- |
| `year` | 编号 | `2011`, (中文(简体) ), `2015`, (中文(简体) ), `2016`, (中文(简体) ), `2017`, (中文(简体) ), `2018`, (中文(简体) ), `2019`, (中文(简体) ), `2020`, (中文(简体) ), `2021`, (中文(简体) ), `2022`, (中文(简体) ), `2023`, (中文(简体) ), `2024`, (中文(简体) ), `2025` | `2025` | 目标ES年. 之后引入的特征是一个错误: 二进制/octal literal和模板 literals需要2015, BigInt需要2020,数字分隔符需要2021. |
| `mode` | 字符串 | `"jsonv"`, (中文(简体) ), `"json5"`, (中文(简体) ), `"json"` | `"jsonv"` | 解析模式 . `"jsonv"` 允许选定年份的每个jsonv特性, `"json5"` 仅用于JSON5 `"json"` 为了严格的JSON。 插件通过模式时没有改变,所以它执行的是 `@cldmv/jsonv` 执行 : `@cldmv/jsonv` 1.1.0, (中文(简体) ), `"json"` 拒绝评论,其他JSON和JSON5限制尚未执行. |
| `strictBigInt` | 布尔 | `true`, (中文(简体) ), `false` | `false` | 何时 `true`,安全范围以外的整数(±9007199254740991),无 `n` 后缀是一个错误。 何时 `false`,它被读取为 BigInt. |
| `strictOctal` | 布尔 | `true`, (中文(简体) ), `false` | `false` | 何时 `true`,一个遗留的八进制文字,例如 `0755` 是一个错误; `0o755` 仍然允许. |
| `allowInternalReferences` | 布尔 | `true`, (中文(简体) ), `false` | `true` | 何时 `true`内部参考资料`backup: port`, (中文(简体) ), `server.port`, (中文(简体) ), `` `${host}` ``) 已解决,未定义或循环引用是错误。 何时 `false`,则未解决,没有报告. |

其他任何密钥,或允许的密钥外的值,都是配置错误(a) `TypeError` 名称选项).

三个 `@cldmv/jsonv` 解析选项被故意不接受 :

-   `reviver`:一个复活器只会转换被评价的值,而林丁则不会使用该值.
-   `preserveComments`: AST 总是带评论,所以内含 `eslint-disable` 评论和规则可以看到它们.
-   `tolerant`:插件控制解析错误的收集方式.

### 内置配置

通常的 ESLint 评论在内部工作 `.jsonv` 文件 : `// eslint-disable`, (中文(简体) ), `/* eslint-disable <rule> */`, (中文(简体) ), `/* eslint-enable */`, (中文(简体) ), `// eslint-disable-line`, (中文(简体) ), `// eslint-disable-next-line`,以及 `/* eslint <rule>: "off" */` 规则配置.

### 写入规则

这个 `jsonv/jsonv` 语言将文档暴露为从 `@cldmv/jsonv`是因为 `parseToAst()`每个节点都有一个 `loc` (一行和一列)和a `range`,因此报告该节点上的节点地,规则可以使用节点类型和选择器:

| 节点类型 | 儿童 | 页:1 |
| --- | --- | --- |
| `Program` | `body` | 该文件; `body` 是根值. `comments` 财务报告和审定财务报表 `tokens` 挂断它. |
| `ObjectExpression` | `properties` | `{ ... }` |
| `Property` | `key`, (中文(简体) ), `value` | `key` 是一个 `Literal` (引用或数字键)或 `Identifier` (未引用密钥). |
| `ArrayExpression` | `elements` | `[ ... ]` |
| `Literal` | —— 说 | 字符串,数字, BigInt (`bigint` 拿着数字,布林斯, `null`, (中文(简体) ), `Infinity`, (中文(简体) ), `NaN`· ; `raw` 是源文本. |
| `Identifier` | —— 说 | 未引用的密钥, 或诸如 `backup: port`。 。 。 . |
| `MemberExpression` | `object`, (中文(简体) ), `property` | 虚构的内部参考资料,例如 `server.port`。 。 。 . |
| `TemplateLiteral` | `quasis`, (中文(简体) ), `expressions` | 一个反向字符串 `${...}` 插值( 平面回击字符串是 `Literal`) (中文(简体) ). |
| `TemplateElement` | —— 说 | 模板的字面部分. |

```javascript
// Report every string value containing "TODO", on the string itself
create(context) {
  return {
    "Property > Literal.value"(node) {
      if (typeof node.value === "string" && node.value.includes("TODO")) {
        context.report({ node, message: "Unexpected TODO." });
      }
    }
  };
}
```

## 支持的特性

### ES2011(JSON5基地)

-   单行`//`)和多线(`/* */`评论
-   对象和阵列中的轨迹逗号
-   未引用的对象密钥
-   单引用字符串
-   十六进制字数`0xFF`(中文(简体) )
-   领先/累进小数点(`.5`, (中文(简体) ), `5.`(中文(简体) )
-   明确的正向标志( :`+5`(中文(简体) )
-   `Infinity`, (中文(简体) ), `-Infinity`, (中文(简体) ), `NaN`
-   多行字符串并有回击续作
-   **通过赤裸的识别资料进行内部参考**数字 : `{ port: 8080, backup: port }`

### ES2015(ES6)

-   二进制字数( E)`0b1010`(中文(简体) )
-   八角形正文(`0o755`,还有遗产 `0755`(中文(简体) )
-   模板字符串( 回击字符串)
-   **内部参考的模板插值**数字 : `` url: `http://${host}:${port}` ``

### ES2020 (英语)

-   BigInt 字义`9007199254740992n`(中文(简体) )
-   六进制/二进制/八入式

### ES2021 (英语)

-   数字分隔符`1_000_000`, (中文(简体) ), `0xFF_AA`, (中文(简体) ), `0b1111_0000`(中文(简体) )

## 示例

**配置( c). jsonv :**

```jsonv
{
  // Server configuration with internal references
  host: "localhost",
  port: 8080,
  
  // Template interpolation
  url: `http://${host}:${port}`,
  
  // ES2021 numeric separators
  maxConnections: 1_000_000,
  
  // ES2020 BigInt
  userId: 9007199254740993n,
  
  // ES2015 binary flags
  permissions: 0b1111_0000,
  
  // Nested reference
  monitoring: {
    healthCheck: url
  }
}
```

## 许可证

[![GitHub license](https://img.shields.io/github/license/CLDMV/jsonv-eslint-plugin-jsonv.svg?style=for-the-badge&logo=github&logoColor=white&labelColor=181717)](https://github.com/CLDMV/jsonv-eslint-plugin-jsonv/blob/HEAD/LICENSE) [![npm license](https://img.shields.io/npm/l/%40cldmv%2Feslint-plugin-jsonv.svg?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837)](https://www.npmjs.com/package/@cldmv/eslint-plugin-jsonv)

阿帕奇-2.0 ©新来/ CLDMV

## 常见问题

### @cldmv/eslint-plugin-jsonv 是什么？

@ cldmv/jsonv 文件的 ESLint 插件

### 如何安装 @cldmv/eslint-plugin-jsonv？

在项目目录运行 npm install @cldmv/eslint-plugin-jsonv，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：eslint（^9\.13\.0 \|\| ^10\.0\.0）、@cldmv/jsonv（^1\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cldmv/eslint-plugin-jsonv 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cldmv/eslint-plugin-jsonv 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cldmv/eslint-plugin-jsonv 需要什么版本的 Node\.js？

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

### @cldmv/eslint-plugin-jsonv 可以商用吗？

@cldmv/eslint-plugin-jsonv 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cldmv/eslint-plugin-jsonv 的下载量有多少？

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

### @cldmv/eslint-plugin-jsonv 还在维护吗？

最新版本 1\.1\.2 发布于 2026/11/07（2 天前）；至今共发布 15 个版本，其中过去 12 个月发布了 15 个；首次发布于 2026/01/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。