# @cepharum/quoting-db 中文文档

规范地址：https://npmcn.com/package/%40cepharum/quoting-db/

版本：1\.3\.0
npm 元数据更新时间：2026-01-19T21:55:42.112Z
中文译文更新时间：2026-11-09T07:59:34.307Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cepharum/quoting-db
原文对照：https://npmcn.com/package/%40cepharum/quoting-db/?lang=original
项目主页：https://gitlab.com/cepharum-foss/quoting-db#readme
源码仓库：https://gitlab.com/cepharum-foss/quoting-db

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

- 包体积（解压后）：148 kB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2024-06-16T19:43:41.057Z
- 最新版本发布：2026-01-19T21:55:41.949Z
- 近 30 天下载量：4520（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 1 个）

## 中文简介

用于配置 shell 引用方法的记录集

## 安装

```sh
npm install @cepharum/quoting-db
```

也可以使用：`pnpm add @cepharum/quoting-db`、`yarn add @cepharum/quoting-db`、`bun add @cepharum/quoting-db`

## README

# 贝壳引用 DB

一组 JSON 编码配置, 用于在引用贝壳时逃避参数 .

## 许可证

[麻省理工学院](https://npmcn.com/package/%40cepharum/quoting-db/LICENSE)

## 关于

这个软件包是为了记录和考虑现有贝壳的不同要求,以便正确逃出参数,防止意外的副作用,例如由于通过功能字符.

此套件中的所有配置都是通过测试不同的方式来逃避ASCII代码范围内的每一个特殊字符,同时使用和不包入引号. 由此而来的记录可以直接从JSON文件中读取或通过某种便利帮助方法来读取.

> **说清楚:** 在代码中引用参数不需要先进行任何测试. 这里提到的所有测试都是提前进行的,以生成配置文件. 您的代码将简单地使用这些配置文件,以正确决定何时使用基于一个 _可选择_ (!) 选中的外壳.

### 测试程序

评估外壳的测试基于两个脚本,其中一个脚本反复引用另一个脚本传递一些数据,由后一脚本显示. 然后根据第二个脚本是否按预期收到数据来评估由此产生的产出.

测试内容包括在ASCII代码页面中的特殊字符和白空间. 他们试图在没有任何逃逸的情况下通过他们,并且有不同的共同逃跑方式。 此外,他们还检查引用一个论点如何影响结果,以及被测试的字符如何与正文字母结合工作.

在以Debian为基地的多克容器中测试了多枚Linux壳. 窗口 `cmd.exe` 财务报告和审定财务报表 `powershell.exe` 已在基于 Windows 11 的设备上进行了手动测试.

## 配置

对于每个被测试的外壳,有一个JSON文件,描述在使用其中任一外壳时为引用和逃避论据而准备的测试结果. 每个文件的数据被分为每个字符可选地用于包扎一个参数的单独配置. 此字符要么是使用不附加引用的空字符串, 要么 `"` 或者说 `'` 用于使用该字符来包装参数。 引用字符的配置可能缺失,以防被测试的外壳在测试时无法相应处理包裹的参数.

每个引用字符的配置都包含这些属性:

-   `mapPattern` 是含有正则表达式的字符串,该表达式与需要回避的任何字符相匹配.
-   `map` 将每个需要逃跑的人物 都映射到其中之一的逃生序列中.
-   `rejectPattern` 是一个带有另一个正则表达式的字符匹配的字符串,完全无法被逃脱. 匹配此模式的参数应被拒绝, 除非有一个不同的引用字符的配置支持它们 .
-   `invalid` 是无法被隐藏到 `true` 用于简化的外观.
-   `prevent` 地图主要用于信息目的。 它标记了那些不应该用前作回击和/或注意来逃脱的人物,因为这些组合将被所引用的脚本所看到. 在使用前面描述的图案时,忽略这幅地图是安全的.

此外,还有一个Javascript模块,提供所有配置的预编译集,用于简化集成,例如与同步工作代码. 这种收集仅限于引用过程所必需的信息,因此缺乏每个外壳和属性的基本元信息 `invalid` 财务报告和审定财务报表 `prevent` 如上文所述,每个引用字符的配置.

## 使用量

所有配置都作为专门的JSON文件提供,每个文件都提及一个被测试的外壳. 你可以用它们做你想做的事.

```javascript
const ashConfiguration = await import( "@cepharum/quoting-db/db/ash.json" );
```

这个例子需要支持导入 JSON 模块. 获取 shell 配置的另一种方法由辅助函数提供:

```javascript
const { getShellConfiguration } = require( "@cepharum/quoting-db" );

const ashConfiguration = await getShellConfiguration( "ash" );
```

此配置可用于引用参数, 引用子进程 :

```javascript
import { spawn } from "node:child_process";
import { getShellConfiguration, quote } from "@cepharum/quoting-db";

const configuration = await getShellConfiguration();
const args = [ "--opt", "some argument with space", "--filter", "!$%><" ];
const quoted = args.map( arg => quote( arg, configuration ) );

const child = spawn( "some-tool", quoted, {
  shell: true,
} );
```

在这里,帮助方法 `getShellConfiguration()` 财务报告和审定财务报表 `quote()` 被使用.

-   `getShellConfiguration()` 承诺当前系统默认 shell 的配置 。 你可以提供不同的外壳名称作为论证. 生成的配置可以随同使用 `quote()` 函数.
    
-   `quote( rawArgument, configuration )` 返回基于 shell 给定配置的原始参数的静态版本。 如果提供的参数中包含完全无法逃脱的字符,它可能会抛出.
    

### 同步处理

如果您的代码需要同步工作, 从指定的 JSON 文件获取一个完整的配置可能不是一个选项 。 图书馆提供了JSON文件预编集,作为Javascript模块,涵盖引用所需的所有信息.

因此,对前一个例子作相应修改的版本将是这样:

```javascript
import { spawn } from "node:child_process";
import { getShellConfigurationSync, quote } from "@cepharum/quoting-db";

const configuration = getShellConfigurationSync();

const args = [ "--opt", "some argument with space", "--filter", "!$%><" ];
const quoted = args.map( arg => quote( arg, configuration ) );

const child = spawn( "some-tool", quoted, {
  shell: true,
} );
```

-   `getShellConfigurationSync()` 是同步对应的 `getShellConfiguration()`。它返回当前系统默认 shell 的配置。 你可以提供不同的外壳名称作为论证. 生成的配置可以作为第二个参数到 `quote()` 函数.

### 其他 API 元素

-   `getShellName()` 是内部使用的帮助函数 `getShellConfiguration()` 财务报告和审定财务报表 `getShellConfigurationSync()`它提供了当前系统默认外壳的正态名称。 您也可以提供所使用的 shell 路径名 `shell` 选择节点 `spawn()` 方法。 在这种情况下,返回给定 shell 的正态基名 .
    
-   每个外壳减少配置的编译集合被曝光为 `configurationPerShell`。 。 。 .
    
    ```javascript
    import { configurationPerShell, quote } from "@cepharum/quoting-db";
    
    const quoted = quote( "$ome argument <to> e%scape", configurationPerShell.ash );
    ```

## 常见问题

### @cepharum/quoting-db 是什么？

用于配置 shell 引用方法的记录集

### 如何安装 @cepharum/quoting-db？

在项目目录运行 npm install @cepharum/quoting-db，或使用 pnpm add / yarn add / bun add。

### @cepharum/quoting-db 支持 TypeScript 吗？

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

### @cepharum/quoting-db 支持 ESM 还是 CommonJS？

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

### @cepharum/quoting-db 可以商用吗？

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

### @cepharum/quoting-db 的下载量有多少？

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

### @cepharum/quoting-db 还在维护吗？

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