# @davidwells/dx-args 中文文档

规范地址：https://npmcn.com/package/%40davidwells/dx-args/

版本：0\.2\.2
npm 元数据更新时间：2026-06-23T06:48:43.519Z
中文译文更新时间：2026-11-11T16:13:01.700Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40davidwells/dx-args
原文对照：https://npmcn.com/package/%40davidwells/dx-args/?lang=original
项目主页：https://github.com/DavidWells/markdown-magic#readme
源码仓库：https://github.com/DavidWells/markdown-magic

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

- 包体积（解压后）：28.2 kB，8 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=14\.0\.0
- 运行依赖：4 个
- 首次发布：2026-05-30T04:12:11.954Z
- 最新版本发布：2026-06-23T06:48:43.417Z
- 近 30 天下载量：27216（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

用于接受松散的密钥/值语法, globs 和 typo- 耐用长旗的 CLIs 的原谅 argv 解析器 .

## 安装

```sh
npm install @davidwells/dx-args
```

也可以使用：`pnpm add @davidwells/dx-args`、`yarn add @davidwells/dx-args`、`bun add @davidwells/dx-args`

## README

# @davidwells/dx-args (英语)

用于 CLIs 的原谅 argv 解析器, 当有人输入一个稍有不完美的命令时, 它应该继续工作 .

`@davidwells/dx-args` 保留 `oparser` 作为值解析器。 它增加了argv常态,文件/glob分组,单盘长选项恢复,以及周围的可预见结果形状.

```js
const { dxParse } = require('@davidwells/dx-args')

const result = dxParse(['-files', 'README.md', '-dry'])

console.log(result.mergedOptions)
// { files: 'README.md', dry: true }

console.log(result.globGroups)
// [{ key: 'files', rawKey: '-files', values: ['README.md'] }]
```

## 安装

```sh
npm install @davidwells/dx-args
```

## API 密码

```js
const {
  dxParse,
  getGlobGroupsFromArgs,
  splitOutsideQuotes,
} = require('@davidwells/dx-args')
```

### `dxParse(argv, opts)`

解析一个 argv 数组并返回 a `ParseResult`。 。 。 .

```js
const result = dxParse(['--stage', 'prod', 'cool', '=', 'true'])

console.log(result.mergedOptions)
// { stage: 'prod', cool: true }
```

### `getGlobGroupsFromArgs(argv, opts)`

将文件和类似 glob 的值提取到分组集合中 .

```js
const result = getGlobGroupsFromArgs(
  ['--files', 'README.md', 'docs/**/*.md'],
  { globKeys: ['files'] }
)

console.log(result.globGroups)
// [{ key: 'files', rawKey: '--files', values: ['README.md', 'docs/**/*.md'] }]
```

### `splitOutsideQuotes(input)`

在保存引用的字符串、对象、阵列和 `key = value` 表单.

```js
splitOutsideQuotes('name = "David Wells" config={ enabled: true }')
// ['name="David Wells"', 'config={ enabled: true }']
```

## 接受输入表

| 投入 | `mergedOptions` |
| --- | --- |
| `--stage prod` | `{ stage: 'prod' }` |
| `--stage=prod` | `{ stage: 'prod' }` |
| `stage = prod` | `{ stage: 'prod' }` |
| `stage=prod` | `{ stage: 'prod' }` |
| `-stage prod` | `{ stage: 'prod' }` |
| `-f README.md` | `{ f: 'README.md' }` |
| `--no-cache` | `{ cache: false }` |
| `--count 3` | `{ count: 3 }` |
| `--items=[1,2,3]` | `{ items: [1, 2, 3] }` |

文件及类似光彩的值也会通过 `globGroups`。 。 。 .

```js
const result = dxParse(['README.md', 'docs/**/*.md', '--stage', 'dev'])

console.log(result.globGroups)
// [{ key: '', rawKey: '', values: ['README.md', 'docs/**/*.md'] }]

console.log(result.mergedOptions)
// { stage: 'dev' }
```

## 结果形状

```ts
interface GlobGroup {
  key: string
  rawKey: string
  values: Array<string | RegExp>
}

interface ParseResult {
  rawArgv: string
  leadingCommands: string[]
  globGroups: GlobGroup[]
  extraParse: Record<string, unknown>
  mriOptionsOriginal: Record<string, unknown>
  mriOptionsClean: Record<string, unknown>
  mriDiff: boolean
  yargsParsed: string
  mergedOptions: Record<string, unknown>
}
```

大多数打电话者应使用:

-   `mergedOptions` 用于解析选项.
-   `globGroups` 用于文件和光泽工作流程.
-   `leadingCommands` 当一个 CLI 在选项前有类似命令的主词时 .

其余领域是诊断:

-   `extraParse` 这是 `oparser`\- 阿尔格夫正常化后得出的分析结果.
-   `mriOptionsOriginal` 原生为 `mri` 结果.
-   `mriOptionsClean` 实值 `mri` 在清理了诸如来自 `-stage`。 。 。 .
-   `mriDiff` 当清理更改时是真实的 `mri` 结果.
-   `yargsParsed` 不活动;它目前是一个兼容/调试字段.

## 球组

`@davidwells/dx-args` 组文件外观和光滑外观参数,这样CLIs就可以从普通选项中分别处理文件.

```js
dxParse(['--files', 'README.md', 'docs/**/*.md']).globGroups
// [{ key: 'files', rawKey: '--files', values: ['README.md', 'docs/**/*.md'] }]
```

空白文件和 glob 值使用空密钥 :

```js
dxParse(['README.md', 'docs/**/*.md']).globGroups
// [{ key: '', rawKey: '', values: ['README.md', 'docs/**/*.md'] }]
```

自定义 glob 密钥可配置 :

```js
dxParse(['--ignore', 'dist/**/*.md'], {
  globKeys: ['files', 'file', 'path', 'ignore']
}).globGroups
// [{ key: 'ignore', rawKey: '--ignore', values: ['dist/**/*.md'] }]
```

贝壳扩展的文件列表被故意不作为主命令处理:

```js
const result = dxParse(['README.md', 'NOTES.md', 'build', '=', 'false'])

console.log(result.globGroups)
// [{ key: '', rawKey: '', values: ['README.md', 'NOTES.md'] }]

console.log(result.mergedOptions)
// { build: false }
```

包含的值 `node_modules/` 正在从 glob 组过滤.

## 复制值

重复的旗帜默认是最后的- write- wins .

```js
dxParse(['--stage', 'dev', '--stage', 'prod']).mergedOptions
// { stage: 'prod' }
```

累积是明确的:

```js
dxParse(['--tag', 'one', '--tag', 'two'], {
  accumulate: ['tag']
}).mergedOptions
// { tag: ['one', 'two'] }
```

解析器目前接受三个累积选项名:

-   `accumulate`
-   `accumulateFlags`
-   `arrayKeys`

偏爱 `accumulate` 在新代码.

## 单一 Dash 政策

多特征的单段选项被视为允许长段选项:

```js
dxParse(['-stage', 'prod']).mergedOptions
// { stage: 'prod' }
```

当值看起来像文件时, 也起作用 :

```js
dxParse(['-config', 'md.config.js']).mergedOptions
// { config: 'md.config.js' }
```

单独的短旗仍然工作 :

```js
dxParse(['-l', '-a', '-h']).mergedOptions
// { l: true, a: true, h: true }
```

短组是选入的,因为它们与允许长时间恢复选项相冲突:

```js
dxParse(['-abc']).mergedOptions
// { abc: true }

dxParse(['-abc'], {
  allowShortClusters: true,
  shortFlags: ['a', 'b', 'c']
}).mergedOptions
// { a: true, b: true, c: true }
```

## 标记下魔法集成

魔法用途 `dxParse` 作为它的CLI解析边界.

标记下魔法地图解析器输出如下 :

-   `file`, (中文(简体) ), `files`, (中文(简体) ), `path`,则赤色文件组变为 `config.files`。 。 。 .
-   `ignore` 组成为 `config.ignore`。 。 。 .
-   其它 `mergedOptions` 成为Markdown Magic Cconfig 覆盖.
-   `output` 财务报告和审定财务报表 `outputDir` 正常化发生在Markdown Magic,不是 `@davidwells/dx-args`。 。 。 .

示例 Markdown 魔法命令 :

```sh
md-magic -files README.md -config md.config.js -dry
md-magic --path "docs/**/*.md" --ignore "dist/**/*.md"
```

## 调试

软件包包含一个打印完整剖析结果的 CLI :

```sh
dx-args -files README.md -config md.config.js -dry
```

调试时, 请检查:

-   `mergedOptions`
-   `globGroups`
-   `mriOptionsOriginal`
-   `mriOptionsClean`
-   `mriDiff`

## 已知差距

-   以空格分隔列表抓取 `--numbers 1 2 3 --strings a b c` 尚未支持.
-   带有引号的真 shell argv 应该作为数组进行测试, 而不仅仅是字符串相接的固定装置 .
-   诊断领域可移入a `debug` 或者说 `trace` 在稳定之前的字段 `1.0.0`。 。 。 .
-   `node_modules/` 过滤器目前被构建为 glob 分组 .
-   `--` 休息通道应在作为公共API记录之前加以规定和测试.

## 常见问题

### @davidwells/dx-args 是什么？

用于接受松散的密钥/值语法, globs 和 typo- 耐用长旗的 CLIs 的原谅 argv 解析器 \.

### 如何安装 @davidwells/dx-args？

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

### @davidwells/dx-args 支持 TypeScript 吗？

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

### @davidwells/dx-args 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @davidwells/dx-args 需要什么版本的 Node\.js？

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

### @davidwells/dx-args 可以商用吗？

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

### @davidwells/dx-args 的下载量有多少？

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

### @davidwells/dx-args 还在维护吗？

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