# @eraserlabs/diagrams-cli 中文文档

规范地址：https://npmcn.com/package/%40eraserlabs/diagrams-cli/

版本：0\.5\.2
npm 元数据更新时间：2026-11-11T18:26:59.611Z
中文译文更新时间：2026-11-13T20:44:31.462Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40eraserlabs/diagrams-cli
原文对照：https://npmcn.com/package/%40eraserlabs/diagrams-cli/?lang=original
项目主页：https://github.com/eraserlabs/eraser-diagrams
源码仓库：https://github.com/eraserlabs/eraser-diagrams

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

- 包体积（解压后）：56.2 kB，29 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：^22\.23\.4 \|\| ^24\.22\.1 \|\| \>=26\.12\.1
- 运行依赖：2 个
- 首次发布：2026-08-19T03:42:05.375Z
- 最新版本发布：2026-11-11T18:26:59.221Z
- 近 30 天下载量：5187（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

Eraser Diagrams的命令行界面:通过@eraserlabs/diagrams渲染和验证图JSON.

## 安装

```sh
npm install @eraserlabs/diagrams-cli
```

也可以使用：`pnpm add @eraserlabs/diagrams-cli`、`yarn add @eraserlabs/diagrams-cli`、`bun add @eraserlabs/diagrams-cli`

## README

# @eraserlabs/diagrams-cli (英语)

## 导言

`@eraserlabs/diagrams-cli` 是命令行接口 [擦除图](https://npmcn.com/package/README.md)它使图表 JSON 变成 PNG 或 HTML ,并在没有浏览器的情况下验证文档,使用 [`@eraserlabs/diagrams`](https://npmcn.com/package/%40eraserlabs/diagrams/)。 。 。 .

## 使用量

```bash
npm install -D @eraserlabs/diagrams-cli
npx eraser-diagrams render diagram.json -o diagram.png
```

需要Node.js 22.23.4+, 24.22.1+, 或 26.12.1+, 以及机器上的铬-家族浏览器(不捆绑).

```text
eraser-diagrams render <input...>     Render diagram JSON to PNG or HTML (needs Chromium)
eraser-diagrams validate <input...>   Validate diagram JSON without a browser
eraser-diagrams registry              Print the tag registry as JSON
eraser-diagrams schema <tag>          Print the JSON Schema of one tag
eraser-diagrams init                  Write eraser-diagrams.config.json in the current directory
```

`<input>` 是文件路径或 `-` 为斯丁。 一些投入共享了一台暖气浏览器. 接受的文件为: `{ "elements": [...] }` 或拆分 `{ "entities": [...], "connections": [...] }`空 JSON 阵列失败 `E_ENVELOPE`A级 `{ "definition": { "elements": [...] } }` 包装被抬起,上面有条纸条.

### 提供选项

| 旗帜 | 默认 | 效果 |
| --- | --- | --- |
| `-o, --out <path>` | `<input>.<format>` 在输出目录中(`diagram.<format>` 用于 stdin) | 单个输入输出文件 . `-o -` 将字节写入 stdout . |
| `--out-dir <dir>` | 当前目录 | 输出去处; 缺失时创建 . |
| `-f, --format png|html` | `png` | 输出格式。 HTML 引用每个字体的来源(`inline: true` 嵌入文件面孔). |
| `--scale <n>` | `1` | PNG 像素密度 (% 1)`deviceScaleFactor`· ; `2` 视网膜。 为 HTML 忽略 . |
| `--transparent` | 关 | 保持PNG背景透明. 忽略 HTML; 作者填充仍然可见 . |
| `--pages <n>` | `1` | 温暖的 Chromium 页面池; 更多的页面同时提供更多的输入 . |
| `--chromium-path <path>` | 见下文 | 铬可执行文件. |
| `--fonts <path>` | 库存字体 | 字体配置 JSON 文件 . |
| `--icon-base-url <url>` | Eraser 的公共目录 | 图标主机 : `<url>/<name>.svg`。 。 。 . |
| `--icon-cache-dir <dir>` | 无 | 上盘图标缓存 . |
| `--unknown-icon placeholder|error` | `placeholder` | 未知图标名称:占位符 glyph + 警告,或硬错误. |
| `--json` | 关 | 机器可读的 stdout上的报告(没有其他的去 stdout). |
| `--fail-on-warning` | 关 | 在报告任何警告(包括已退化的字体)时退出 1 . |
| `-q, --quiet` | 关 | 没有输入状态行; 失败仍在打印 . |
| `--debug` | 关 | 阶段计时和Stderr上的配置/铬出处. |

对于具有透明背景的巴布亚新几内亚:

```bash
eraser-diagrams render diagram.json --transparent --scale 2 -o diagram.png
```

`validate` 接受 `--json`, (中文(简体) ), `--fail-on-warning`, (中文(简体) ), `--quiet`, (中文(简体) ), `--debug`。 。 。 .

### 全球备选方案

| 旗帜 | 效果 |
| --- | --- |
| `-c, --config <path>` | 要使用的配置文件 . |
| `--no-config` | 忽略配置文件 . |
| `--print-config` | 打印有效配置(合并后)并退出. |
| `-h, --help`, (中文(简体) ), `-v, --version` | 帮助/ 版本. |

## 铬

优先发言: `--chromium-path` > 翻译: `CHROMIUM_PATH` > 翻译: `chromiumPath` 在配置文件 > 自动检测中。 自动探测探测器 通常的Chrome和Chromium 安装位置 并报告它选择的. `eraser-diagrams init` 将检测到的路径写入配置文件, 使其保持被绑定 .

## 配置文件

`eraser-diagrams.config.json` 是通过从当前目录上走来找到的(在包含 `.git`)),或给予 `--config` 或者说 `ERASER_DIAGRAMS_CONFIG`优先是 **旗帜 > 环境 > 配置文件 > 默认**。相对于文件本身的目录,文件解析中的相对路径。 未知密钥被拒绝 .

```json
{
  "chromiumPath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
  "format": "png",
  "outDir": "./diagrams",
  "deviceScaleFactor": 2,
  "pages": 2,
  "icons": {
    "baseUrl": "https://storage.googleapis.com/eraser-public-assets/canvas-icons/",
    "cacheDir": "./.eraser/icons",
    "timeoutMs": 5000,
    "cacheTtlMs": 86400000,
    "onUnknown": "placeholder"
  },
  "fonts": "./fonts.json",
  "library": "./my-library.mjs",
  "overrides": "./my-overrides.mjs",
  "failOnWarning": false
}
```

| 密钥 | 类型 | 含义 |
| --- | --- | --- |
| `chromiumPath` | 字符串 | 铬可执行文件. |
| `format` | `"png"` | `"html"` | 默认 `--format`。 。 。 . |
| `outDir` | 字符串 | 默认 `--out-dir`。 。 。 . |
| `deviceScaleFactor` | 编号 | 默认 `--scale`。 。 。 . |
| `transparent` | 布尔 | 默认 `--transparent` (虚也. |
| `pages` | 编号 | 默认 `--pages`。 。 。 . |
| `icons.baseUrl`, (中文(简体) ), `icons.cacheDir`, (中文(简体) ), `icons.timeoutMs`, (中文(简体) ), `icons.cacheTtlMs` |  | 图标加载器设置( E)`createEraserIconLoader`) (中文(简体) ). |
| `icons.onUnknown` | `"placeholder"` | `"error"` | 未知图标策略 . |
| `fonts` | 对象或字符串 | A 类 `FontsConfig` 对象,或 JSON 文件的路径. `path` 编号 : `cachePath` 里面有与申报他们的档案相对立的意志. |
| `library` | 字符串 | ES 模块路径导出 `library` (单位:千美元) `AuthoredLibrary`)和可选 `normalizers`。替换股票库;见 [计算机化.md](https://npmcn.com/package/CUSTOMIZATION.md)。 。 。 . |
| `overrides` | 字符串 | ES 模块路径导出 `overrides` (单位:千美元)`{ templates: TemplateFile[] }`: 组件按名称合并到库上. |
| `failOnWarning` | 布尔 | 默认 `--fail-on-warning`。 。 。 . |

除了别的事 `--format` 而输出路径在浏览器靴子时被固定,因此适用于整批.

## 输出和退出代码

状态到 stderr,每输入一行,然后是问题:

```text
ok    diagram.json  → out/diagram.png  412 ms  1 warning
  warning W_UNKNOWN_ICON /elements/1/icon (Icon#api) — Unknown icon "nodejs"; using a placeholder glyph.
FAIL  other.json  E_UNKNOWN_TAG
  error   E_UNKNOWN_TAG /elements/0 (Shpe) — Unknown tag "Shpe". Did you mean "Shape"?
```

`--json` 在 stdout 上打印一个报表:

```json
{
  "ok": false,
  "degradedFonts": [],
  "results": [
    {
      "input": "diagram.json",
      "out": "out/diagram.png",
      "ok": true,
      "errors": [],
      "warnings": [],
      "ms": 412
    },
    {
      "input": "other.json",
      "ok": false,
      "errors": [
        {
          "code": "E_UNKNOWN_TAG",
          "severity": "error",
          "path": "/elements/0",
          "message": "Unknown tag \"Shpe\".",
          "suggestion": "Shape"
        }
      ],
      "warnings": []
    }
  ]
}
```

| 退出代码 | 含义 |
| --- | --- |
| `0` | 每次输入都成功(允许警告,除非 `--fail-on-warning`) (中文(简体) ). |
| `1` | 至少一个输入失败:无法读取的文件,无效的JSON,验证错误,或失败的渲染. |
| `2` | 引用本身失败:旗子不好,配置文件不好,没有Chromium,自定义库被拒绝. |

`Ctrl-C` 退出前关闭铬.

## 常见问题

### @eraserlabs/diagrams-cli 是什么？

Eraser Diagrams的命令行界面:通过@eraserlabs/diagrams渲染和验证图JSON\.

### 如何安装 @eraserlabs/diagrams-cli？

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

### @eraserlabs/diagrams-cli 支持 TypeScript 吗？

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

### @eraserlabs/diagrams-cli 支持 ESM 还是 CommonJS？

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

### @eraserlabs/diagrams-cli 需要什么版本的 Node\.js？

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

### @eraserlabs/diagrams-cli 可以商用吗？

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

### @eraserlabs/diagrams-cli 的下载量有多少？

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

### @eraserlabs/diagrams-cli 还在维护吗？

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