# @clerc/parser 中文文档

规范地址：https://npmcn.com/package/%40clerc/parser/

版本：1\.3\.1
npm 元数据更新时间：2026-02-22T06:19:37.821Z
中文译文更新时间：2026-11-10T01:10:22.085Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40clerc/parser
原文对照：https://npmcn.com/package/%40clerc/parser/?lang=original
项目主页：https://github.com/clercjs/clerc/tree/main/packages/parser#readme
源码仓库：https://github.com/clercjs/clerc

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

- 包体积（解压后）：25.3 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2025-12-10T11:10:54.399Z
- 最新版本发布：2026-02-22T06:19:37.502Z
- 近 30 天下载量：325269（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：41（近 12 个月 41 个）

## 中文简介

克莱克解析器

## 安装

```sh
npm install @clerc/parser
```

也可以使用：`pnpm add @clerc/parser`、`yarn add @clerc/parser`、`bun add @clerc/parser`

## README

# @ clerc/ parser (帮助)

[![NPM version](https://img.shields.io/npm/v/@clerc/parser?color=a1b858&label=)](https://www.npmjs.com/package/@clerc/parser)

一个强大的,轻量级的,灵活的命令行参数解析器.

## 安装

```bash
$ npm install @clerc/parser
$ yarn add @clerc/parser
$ pnpm add @clerc/parser
```

## 使用量

这个软件包的核心是 `parse` 函数。 它需要一系列参数和一个配置对象,并返回包含解析的旗帜、参数和其他有用信息的结构化对象.

```typescript
import { parse } from "@clerc/parser";

const { flags, parameters, unknown } = parse(process.argv.slice(2), {
  flags: {
    // Define your flags here
    port: {
      type: Number,
      alias: "p",
      default: 8080,
    },
    help: {
      type: Boolean,
      alias: "h",
    },
  },
});

console.log("Flags:", flags);
console.log("Parameters:", parameters);
console.log("Unknown args:", unknown);
```

## API 密码

### `parse(args, options)`

#### `args`

-   类型 : `string[]`
-   要解析的命令行参数阵列( 例如 ), `process.argv.slice(2)`) (中文(简体) ).

#### `options`

-   类型 : `ParseOptions`

配置解析器的对象.

-   **`flags`**: 定义要解析的旗帜的对象.
    -   键:旗名 (在骆驼Case中).
    -   数值 : 旗的配置,它可以是类型构造器(`String`, (中文(简体) ), `Number`, (中文(简体) ), `Boolean`)或自定义函数取出字符串并返回解析值或具有以下属性的对象:
        -   `type`:国旗的种类. 可以像一个建筑师 `String`, (中文(简体) ), `Number`, (中文(简体) ), `Boolean`, (中文(简体) ), `Object`,一个构造器的数组(例如, `[String]`),或使用字符串并返回解析值的自定义函数.
        -   `alias`:用于替代名称(例如短旗)的字符串或数组字符串.
    -   `default`: 如果参数中未提供该旗帜的默认值 。 可以是值,也可以是返回值的函数.
    -   `negatable`: (对于布尔人) 是否支持 `--no-<flag>` 语法. 默认为 `true`。 。 。 .
-   **`ignore`**: 有条件停止解析的函数。 它接收到 `type` (单位:千美元)`flag` 或者说 `parameter`)和 `arg` 字符串, 并应当返回 `true` 从此停止分析.

#### 回返

具有下列属性的对象:

-   `flags`: 含有已解析过的旗帜的对象.
-   `parameters`:一系列位置参数.
-   `unknown`: 含有图案中没有定义的旗帜的对象.
-   `doubleDash`: 后面出现的一连串参数 `--`。 。 。 .
-   `ignored`: 由于 `ignore` 函数.

## 特征

### 基本类型

支助 `Boolean`, (中文(简体) ), `String`,以及 `Number`。 。 。 .

```typescript
const { flags } = parse(["--bool", "--str", "hello", "--num", "42"], {
  flags: {
    bool: { type: Boolean },
    str: { type: String },
    num: { type: Number },
  },
});
// flags: { bool: true, str: "hello", num: 42 }
```

### 别名

使用 `alias` 以定义旗帜的短名或替代名.

```typescript
const { flags } = parse(["-b", "-s", "hello"], {
  flags: {
    bool: { type: Boolean, alias: "b" },
    str: { type: String, alias: "s" },
  },
});
// flags: { bool: true, str: "hello" }
```

### 阵列和计数器

-   要收集标记的多值,请使用一个数组类型,如 `[String]`。 。 。 .
-   要计算布尔旗的出错,请使用 `[Boolean]`。 。 。 .

```typescript
// Array of strings
const { flags: arrayFlags } = parse(["--arr", "a", "--arr", "b"], {
  flags: {
    arr: { type: [String] },
  },
});
// arrayFlags: { arr: ["a", "b"] }

// Counter
const { flags: counterFlags } = parse(["-vvv"], {
  flags: {
    verbose: { type: [Boolean], alias: "v" },
  },
});
// counterFlags: { verbose: 3 }
```

### 合并短旗

多布尔短旗可以合并. 组内最后一面旗帜可以取出一个值.

```typescript
// -abc => a=true, b=true, c=true
const { flags: merged } = parse(["-abc"], {
  flags: {
    a: Boolean,
    b: Boolean,
    c: Boolean,
  },
});
// merged: { a: true, b: true, c: true }

// -ab val => a=true, b="val"
const { flags: withValue } = parse(["-ab", "val"], {
  flags: {
    a: Boolean,
    b: String,
  },
});
// or -abval, b is not boolean
const { flags: withValue } = parse(["-abval"], {
  flags: {
    a: Boolean,
    b: String,
  },
});
// withValue: { a: true, b: "val" }
```

### 默认值

提供a `default` 用于不存在的旗帜的值.

```typescript
const { flags } = parse([], {
  flags: {
    str: { type: String, default: "default" },
    num: { type: Number, default: 123 },
    fn: { type: String, default: () => "computed" },
  },
});
// flags: { str: "default", num: 123, fn: "computed" }
```

默认情况下,布尔、计数器、数组和对象在 `default` 未提供:

-   布尔 : `false`
-   计数器 : `0`
-   矩阵 : `[]`
-   对象 : `{}`

### 可忽略的旗帜

布尔旗默认为可忽略 `--no-` 前缀.

如果您想要禁用此行为, 请设定 `negatable: false` 在旗帜配置中。 通过 `--no-<flag>` 然后作为不明旗帜对待.

```typescript
const { flags, unknown } = parse(
  ["--no-cache", "--no-ssl=false", "--no-disable-negate"],
  {
    flags: {
      cache: { type: Boolean, default: true },
      ssl: { type: Boolean, default: true },
      disableNegate: { type: Boolean, negatable: false, default: true },
    },
  },
);
// flags: { cache: false, ssl: true, disableNegate: true }
// unknown: { noDisableNegate: true }
```

### 自定义类型函数

您可以为您提供自定义函数 `type` 用于高级解析逻辑的属性。 该函数收到字符串值并应当返回解析值.

```typescript
// Let's limit port between 1 and 65535
const { flags } = parse(["--port", "8080"], {
  flags: {
    port: {
      type: (value: string) => {
        const parsed = Number.parseInt(value, 10);
        if (Number.isNaN(parsed)) {
          throw new TypeError("Port must be a number!");
        }
        if (parsed < 1 || parsed > 65_535) {
          throw new Error("Port must be between 1 and 65535!");
        }

        return parsed;
      },
    },
  },
});
// flags: { port: 8080 }
```

### 点标记对象

定义标志 `Object` 类型将点注释参数分析成嵌入对象.

```typescript
const { flags } = parse(
  ["--config.port", "8080", "--config.host", "localhost"],
  {
    flags: {
      config: { type: Object },
    },
  },
);
// flags: { config: { port: "8080", host: "localhost" } }
```

多层筑巢也得到支持.

```typescript
const { flags } = parse(
  [
    "--db.host",
    "localhost",
    "--db.port",
    "5432",
    "--db.credentials.user",
    "admin",
    "--db.credentials.password",
    "secret",
  ],
  {
    flags: {
      db: { type: Object },
    },
  },
);
// flags: { db: { host: "localhost", port: "5432", credentials: { user: "admin", password: "secret" } } }
```

### 未知的旗帜

计划内未定义的旗帜在 `unknown` 对象。 如果可能的话, 它们将被转换为布尔 `true`。 。 。 .

```typescript
const { flags, unknown } = parse([
  "--unknown1",
  "--unknown2=foo",
  "--unknown3",
  "bar",
  "--unknown.foo",
]);

// unknown: { unknown1: true, unknown2: "foo", unknown3: "bar", "unknown.foo": true }
```

### 停止分析

使用 `ignore` 函数可以在满足特定条件时停止解析。 随后的论据将添加到 `ignored` 阵列.

```typescript
const { flags, ignored } = parse(["--a", "--b", "stop", "--c"], {
  flags: {
    a: Boolean,
    b: Boolean,
    c: Boolean,
  },
  ignore: (type, arg) => arg === "stop",
});
// flags: { a: true, b: true, c: false }
// ignored: ["stop", "--c"]
```

通过检查 `type`。 。 。 .

```typescript
const { flags, parameters, ignored } = parse(
  ["--allow-all", "./deno.ts", "--param"],
  {
    flags: {
      allowAll: Boolean,
    },
    ignore: (type) => type === "parameter",
  },
);

// flags: { allowAll: true }
// parameters: []
// ignored: ["./deno.ts", "--param"]
```

### 双发`--`(中文(简体) )

参数后 `--` 未解析为旗帜,在 `doubleDash` 阵列.

```typescript
const { flags, doubleDash } = parse(["--foo", "--", "--bar"], {
  flags: {
    foo: Boolean,
    bar: Boolean,
  },
});
// flags: { foo: true, bar: false }
// doubleDash: ["--bar"]
```

## 基准

以Vitest为基准.

```
✓ packages/parser/bench/bench.bench.ts > bench 6267ms
        name                           hz     min     max    mean     p75     p99    p995    p999     rme  samples
    · minimist               684,422.77  0.0012  3.5582  0.0015  0.0013  0.0031  0.0040  0.0222  ±1.50%   342212
    · mri                  2,451,855.02  0.0003  0.2422  0.0004  0.0004  0.0007  0.0009  0.0021  ±0.33%  1225928
    · yargs-parser            90,437.66  0.0092  3.1595  0.0111  0.0103  0.0346  0.0602  0.1311  ±1.42%    45219
    · nopt                   636,086.73  0.0014  0.3214  0.0016  0.0015  0.0027  0.0031  0.0056  ±0.38%   318044
    · type-flag              715,908.28  0.0012  0.3783  0.0014  0.0013  0.0022  0.0027  0.0282  ±0.61%   357955
    · node:util parseArgs  1,204,359.72  0.0007  0.3827  0.0008  0.0008  0.0016  0.0017  0.0047  ±0.56%   602196
    · args-tokens          2,379,934.00  0.0002  0.2923  0.0004  0.0004  0.0010  0.0015  0.0051  ±0.49%  1189967
    · @clerc/parser        2,119,030.30  0.0003  0.2482  0.0005  0.0005  0.0009  0.0011  0.0017  ±0.49%  1059516

BENCH  Summary

  mri - packages/parser/bench/bench.bench.ts > bench
    1.03x faster than args-tokens
    1.16x faster than @clerc/parser
    2.04x faster than node:util parseArgs
    3.42x faster than type-flag
    3.58x faster than minimist
    3.85x faster than nopt
    27.11x faster than yargs-parser
```

## 许可证

[麻省理工学院](https://npmcn.com/package/LICENSE)由 QQ 制作 [筽](https://github.com/so1ve)

## 常见问题

### @clerc/parser 是什么？

克莱克解析器

### 如何安装 @clerc/parser？

在项目目录运行 npm install @clerc/parser，或使用 pnpm add / yarn add / bun add。

### @clerc/parser 支持 TypeScript 吗？

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

### @clerc/parser 支持 ESM 还是 CommonJS？

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

### @clerc/parser 可以商用吗？

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

### @clerc/parser 的下载量有多少？

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

### @clerc/parser 还在维护吗？

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