# @dreamlake/json-layer 中文文档

规范地址：https://npmcn.com/package/%40dreamlake/json-layer/

版本：0\.2\.0
npm 元数据更新时间：2026-10-09T20:05:43.405Z
中文译文更新时间：2026-11-12T23:15:08.134Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40dreamlake/json-layer
原文对照：https://npmcn.com/package/%40dreamlake/json-layer/?lang=original
项目主页：https://github.com/dreamlake-ai/json-layer#readme
源码仓库：https://github.com/dreamlake-ai/json-layer

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

- 包体积（解压后）：19.2 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19
- 运行依赖：0 个
- 首次发布：2026-10-09T20:02:17.297Z
- 最新版本发布：2026-10-09T20:05:43.251Z
- 近 30 天下载量：3236（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

分层的JSON配置:由静态覆盖和运算器组成的JSON行,按顺序解决,每个值的源行.

## 安装

```sh
npm install @dreamlake/json-layer
```

也可以使用：`pnpm add @dreamlake/json-layer`、`yarn add @dreamlake/json-layer`、`bun add @dreamlake/json-layer`

## README

# @dreamlake/json-layer (英语)

JSON上层改变 每行一变.

```sh
npm install @dreamlake/json-layer
```

```ts
import { resolve, explain } from '@dreamlake/json-layer';

const { value, touches } = resolve(base, [
  { id: 'provider', text: providerLayer },
  { id: 'team', text: teamLayer },
]);
explain(touches, 'network.subnets.b'); // { layer: 'team', line: 3, path: [...] }
```

下面的每一个例子都是一个基础,一层,以及结果. 他们作为测试运行.

## 覆盖

对象行合并对象并替换其他所有对象.

```json
{"type": "t3.large", "tags": {"team": "a", "cost": "x"}, "groups": ["sg-1"], "disk": 100}
```

```jsonl
{"type": "g5.xlarge", "tags": {"team": "b"}, "groups": ["sg-2"], "disk": null}
```

```json
{"type": "g5.xlarge", "tags": {"team": "b", "cost": "x"}, "groups": ["sg-2"], "disk": null}
```

线条依序适用.

```json
{}
```

```jsonl
{"a": 1}
{"a": 2, "b": 3}
```

```json
{"a": 2, "b": 3}
```

## 运算符

`[operator, path, ...values]`

### 插入

```json
{"setup": ["apt update"]}
```

```jsonl
["insert", "setup", "pip install -e .", "make"]
["insert", "env.paths", "/opt/bin"]
```

```json
{"setup": ["apt update", "pip install -e .", "make"], "env": {"paths": ["/opt/bin"]}}
```

### 预选

```json
{"setup": ["make"]}
```

```jsonl
["prepend", "setup", "apt update"]
```

```json
{"setup": ["apt update", "make"]}
```

### 工会

```json
{"groups": ["sg-1", "sg-2"]}
```

```jsonl
["union", "groups", "sg-2", "sg-3"]
```

```json
{"groups": ["sg-1", "sg-2", "sg-3"]}
```

### 删除

```json
{"groups": ["sg-1", "sg-2", "sg-1"], "mounts": [{"src": "/a", "dst": "/b"}, {"src": "/c", "dst": "/d"}]}
```

```jsonl
["remove", "groups", "sg-1"]
["remove", "mounts", {"dst": "/b", "src": "/a"}]
```

```json
{"groups": ["sg-2"], "mounts": [{"src": "/c", "dst": "/d"}]}
```

### 删除

```json
{"tags": {"team": "a", "scratch": "yes"}}
```

```jsonl
["delete", "tags.scratch"]
["delete", "tags.missing"]
```

```json
{"tags": {"team": "a"}}
```

### 替换

```json
{"tags": {"team": "a", "cost": "x"}}
```

```jsonl
["replace", "tags", {"team": "b"}]
```

```json
{"tags": {"team": "b"}}
```

### 合并

```json
{"network": {"vpc": "vpc-1", "subnets": {"a": "subnet-a", "b": "subnet-b"}}}
```

```jsonl
["merge", "network.subnets", {"b": "subnet-b2", "c": {"id": "subnet-c"}}]
```

```json
{"network": {"vpc": "vpc-1", "subnets": {"a": "subnet-a", "b": "subnet-b2", "c": {"id": "subnet-c"}}}}
```

### 全值

```json
{"a": 1}
```

```jsonl
["replace", "", {"b": 2}]
["merge", "", {"c": 3}]
```

```json
{"b": 2, "c": 3}
```

## 路径

```json
{}
```

```jsonl
["replace", "a.b.c", 1]
["replace", ["x.y", "z"], 2]
{"p.q": 3}
```

```json
{"a": {"b": {"c": 1}}, "x.y": {"z": 2}, "p.q": 3}
```

## 评论

```json
{"groups": []}
```

```jsonl
// whole lines only

  // indented is fine
["insert", "groups", "sg-1"]
{"url": "https://example.com//kept"}
```

```json
{"groups": ["sg-1"], "url": "https://example.com//kept"}
```

## 没有保留

```json
{}
```

```jsonl
{"$insert": ["x"], "note": "[\"delete\", \"a\"]"}
```

```json
{"$insert": ["x"], "note": "[\"delete\", \"a\"]"}
```

## 错误

```jsonl
{"a": 1}
["insrt", "a", 1]
```

```text
L:2: unknown operator "insrt"
```

```jsonl
{"a": 1} // no trailing comments
```

```text
L:1: not JSON
```

```jsonl
["merge", "a", {
  "b": 1}]
```

```text
L:1: not JSON
```

```json
{"tags": "none"}
```

```jsonl
["insert", "tags", "x"]
```

```text
L:1: insert needs an array at tags
```

## 国 际

```sh
json-layer resolve base.json provider.jsonl team.jsonl
json-layer resolve base.json provider.jsonl team.jsonl --explain network.subnets.b
# network.subnets.b	team.jsonl:3 (network.subnets.b)
json-layer check team.jsonl
```

## 参考文献

| 线条 | 效果 |
| --- | --- |
| `{...}` | 合并对象, 替换其余对象 |
| `["merge", p, {...}]` | 同样,在 `p` |
| `["replace", p, v]` | 设定 `p` 改为 `v` |
| `["delete", p]` | 删除 `p` 如果有的话 |
| `["insert", p, v...]` | 附加到数组 |
| `["prepend", p, v...]` | 添加到阵列前方 |
| `["union", p, v...]` | 未显示的附加值 |
| `["remove", p, v...]` | 删除等值 |
| `// ...` | 注释, 全行 |

-   `p`数字 : `"a.b.c"`,或 `["a.b", "c"]` 当一个键有一个点; `""` 是整个值.
-   失踪父母的产生,除非 `delete` 财务报告和审定财务报表 `remove`。 。 。 .
-   矩阵按值匹配,从不索引.
-   每行一纸.
-   注释行会制作一层非收缩的JSON行.

## 许可证

麻省理工学院

## 常见问题

### @dreamlake/json-layer 是什么？

分层的JSON配置:由静态覆盖和运算器组成的JSON行,按顺序解决,每个值的源行\.

### 如何安装 @dreamlake/json-layer？

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

### @dreamlake/json-layer 支持 TypeScript 吗？

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

### @dreamlake/json-layer 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dreamlake/json-layer 需要什么版本的 Node\.js？

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

### @dreamlake/json-layer 可以商用吗？

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

### @dreamlake/json-layer 的下载量有多少？

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

### @dreamlake/json-layer 还在维护吗？

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