@clerc/parser

中文文档

1.3.1发布于 2026/02/22MITTypeScriptES Module构建来源已验证近 30 天下载 32.5万

克莱克解析器

文档目录18 节

安装
使用量
API 密码
parse(args, options)
特征
基本类型
别名
阵列和计数器
合并短旗
默认值
可忽略的旗帜
自定义类型函数
点标记对象
未知的旗帜
停止分析
双发 -- (中文(简体) )
基准
许可证

@ clerc/ parser (帮助)

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

安装

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

使用量

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

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。。。 .

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 以定义旗帜的短名或替代名.

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

阵列和计数器

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

// 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 }

合并短旗

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

// -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 用于不存在的旗帜的值.

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> 然后作为不明旗帜对待.

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 用于高级解析逻辑的属性。该函数收到字符串值并应当返回解析值.

// 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 类型将点注释参数分析成嵌入对象.

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

多层筑巢也得到支持.

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。。。 .

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

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

停止分析

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

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。。。 .

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 阵列.

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

许可证

麻省理工学院由 QQ 制作筽

版本与发布记录

@clerc/parser 共发布 41 个版本，首次发布于 2025/12/10；过去 12 个月发布了 41 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本	发布日期	距今
`1.3.1`latest	2026/02/22	8 个月前
`1.3.0`	2026/02/22	8 个月前
`1.3.0-beta.2`	2026/02/20	8 个月前
`1.3.0-beta.1`	2026/01/18	9 个月前
`1.2.1`	2026/01/08	10 个月前
`1.2.0`	2026/01/08	10 个月前

关于 @clerc/parser 的常见问题

@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 和提交记录判断。