# @hackylabs/deep-redact 中文文档

规范地址：https://npmcn.com/package/%40hackylabs/deep-redact/

版本：4\.1\.0
npm 元数据更新时间：2026-08-28T08:48:55.992Z
中文译文更新时间：2026-11-17T05:48:46.005Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40hackylabs/deep-redact
原文对照：https://npmcn.com/package/%40hackylabs/deep-redact/?lang=original
项目主页：https://github.com/hackylabs/deep-redact#readme
源码仓库：https://github.com/hackylabs/deep-redact

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

- 包体积（解压后）：292 kB，13 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.18\.0
- 运行依赖：0 个
- 首次发布：2024-07-27T12:53:13.208Z
- 最新版本发布：2026-08-28T08:48:55.652Z
- 近 30 天下载量：344875（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 6 个）

## 中文简介

从对象,阵列和任意字符串(如XML或原始 cookie 数据)中深度编辑敏感数据,并具有可相容,函数先的API.

## 安装

```sh
npm install @hackylabs/deep-redact
```

也可以使用：`pnpm add @hackylabs/deep-redact`、`yarn add @hackylabs/deep-redact`、`bun add @hackylabs/deep-redact`

## README

# 深度编辑

[![npm version](https://badge.fury.io/js/@hackylabs%2Fdeep-redact.svg)](https://badge.fury.io/js/@hackylabs%2Fdeep-redact) [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/hackylabs/deep-redact/blob/main/LICENSE)

@hackylabs/deep-redact是用于Node.js和Deno的由规则驱动的编辑库. 它使你能够表达要编辑什么——一个关键名称,一个路径,一个正格克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克 政策一经初始化就汇编,并在每项请求中重新使用,使之适合高通量生产用途.

图书馆 `fast-redact` 需要为可能出现敏感字段的每个地点提供明确的路径(`a.b.password`, (中文(简体) ), `a.c.password`,....。深重置反转这个:一个单曲 `keys: ['password']` 规则目标 `password` 字段在任意深度。 它还增加了路径编号库无法提供的能力,如部分字符串编辑(瞄准较大值内的敏感模式)和重复结构的通配符路径选择器.

[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/hackylabs)

## 特征

-   **深度不可知关键规则** ——在任何巢穴深度编辑任意字段的名称;不需要路径计数
-   **精确和结构化路径瞄准** ——当需要精确度时,将编辑指向特定地点
-   **Regex 属性匹配** ——通过正则表达式匹配字段名称
-   **子字符串目标** ——编辑一个在较大值内出现的敏感字符串,而不只是全值替换
-   **通关卡和排除路径选择器** 几乎在任何深度处理重复结构(`['addresses.*', { ignore: 'country' }]`)而不列出每个索引
-   **结构化和序列化产出** ——返回活对象图或保证-JSON安全字符串(`serialise: true`(中文(简体) )
-   **内置和自定义变压器** ——超越特定运行时间类型在序列化输出中的表现方式
-   **内设安保** ——通过内存耗竭来防止原型污染和DoS
-   **控制台适配器** - 可选 `console.*` 通过明确的适配器编辑

## 基线

-   节点 `24.14.1`
-   `pnpm@10.33.0`
-   `tsdown`
-   `Vitest`
-   `ESLint`

## 安装

```sh
npm install @hackylabs/deep-redact
pnpm add @hackylabs/deep-redact
yarn add @hackylabs/deep-redact
bun add @hackylabs/deep-redact
```

**德诺** ——将软件包添加到导入地图中(`deno.json`:

```json
{
  "imports": {
    "@hackylabs/deep-redact": "npm:@hackylabs/deep-redact@4.1.0"
  }
}
```

## 快速启动

```ts
import { deepRedact } from '@hackylabs/deep-redact'

const redact = deepRedact({ keys: ['password', 'token'] })

redact({ user: { password: 'secret', safe: 'keep this' }, token: 'abc123', id: 1 })
// { user: { password: '[REDACTED]', safe: 'keep this' }, token: '[REDACTED]', id: 1 }
```

## 基准

由承诺的手工艺品产生 `test/artefacts/benchmarks/speed/`. Node.js 24 LTS, Apple M系列. 1万个暖热后稳定状态.

### TLDR 头条

> **如果原始吞吐量是您的主要制约因素, 您可以接受详尽的路径计数, 使用 [`fast-redact`](https://www.npmjs.com/package/fast-redact) 换句话说.** 它是专为JSON-string最大输出速度而专门建造的,在那种狭义的场景中,它将超越任何规则驱动的库. 当您需要深度不可知的目标、通配符路径、下行编辑或内置的安全保障时使用深重写.

如果你选择快速重写, 注意权衡:

-   **没有深度不可知的关键规则** ——必须明确列举每一个敏感路径
-   **无双通卡( N)`**`路径选择器** - 你不能瞄准目标 `records.**.email` 不列出每个深度
-   **没有子字符串目标** ——仅全值替换;不支持部分字符串编辑
-   **没有序列安全变压器管道** - 没有内置处理 `BigInt`, (中文(简体) ), `Date`, (中文(简体) ), `Map`, (中文(简体) ), `Set`, (中文(简体) ), `Error`, (中文(简体) ), `RegExp`,或 `URL` 数值
-   **没有污染保护原型** - 没有防守 `__proto__` 财务报告和审定财务报表 `constructor.prototype` 注射
-   **没有可配置的深度或节点限制** ——没有通过深巢或过大的有效载荷进行防护

### 结构化产出(`serialise: false`(中文(简体) )

v4, v3, 并快速编辑全部返回一个平版 JavaScript 对象 .

![Speed comparison — structured output](https://npmcn.com/package/%40hackylabs/deep-redact/docs/benchmarks/charts/speed-comparison-non-serialised.svg)

_QQ快取是第三方图书馆,而不是深取的版本. 其被显示为吞吐量参考;其特征设置和保证与深红相异,因此它不是一种相类似比较._

v4 为 **~ 17× 更快 ~** 与基于路径的工作量和 **~ 10× 更快 ~** 关于通配符工作量.

### 序列化产出( E)`serialise: true`(中文(简体) )

所有四个解决方案都返回一个JSON字符串.

![Speed comparison — serialised output](https://npmcn.com/package/%40hackylabs/deep-redact/docs/benchmarks/charts/speed-comparison-serialised.svg)

_• 快速编辑是第三方图书馆;json-stringify-regex是一种天真的本土方法(`JSON.stringify(value).replace(pattern, replacement)`),不是图书馆. 既未进行深红字的结构编辑,也未提供其保证,因此两者都显示为吞吐量参考,而非类似比较._

v4在序列化模式下保持快于v3. 快速重写和json-stringify-regex具有吞吐量优势,因为它们的输出路径完全面向字符串生产.

相对于深红活性v2,序列相加不一:v4在基于路径的工作量上大致平分,而宽重(wildcard)的工作量则较慢. 这笔差额是安全v2的费用没有提供——根据 `serialise: true`,v4 运行生成 `BigInt`, (中文(简体) ), `Date`, (中文(简体) ), `Map`, (中文(简体) ), `Set`, (中文(简体) ), `Error`, (中文(简体) ), `RegExp`,以及 `URL` 它检测和校正了循环引用 而不是扔在它们身上 (通过 `maxNodes`编号 :`maxDepth` (b) 支票是反递增的,增加了可忽略不计的费用。 设定 `onBudgetExceeded: 'truncate'` 无法用 a 关闭 `[TRUNCATED]` 标记而不是投掷。 )

这些安全通行证是内在的 `serialise: true` 无法单独关闭。 如果您不需要这些保证, 想要匹配 v2 的吞吐量( 或者更好), 设置 `serialise: false` 自己开 `JSON.stringify`:结构化输出路径跳过变压器,圆通引用完全通过. 这会恢复V2的取舍 `JSON.stringify` 将弹出 `BigInt` 和通告参考, `Map`编号 :`Set` 序列为 `{}`,以及 `undefined` 被删除.

全速和资源基准结果: [`docs/benchmarks/speed-results.md`](https://npmcn.com/package/%40hackylabs/deep-redact/docs/benchmarks/speed-results.md) 财务报告和审定财务报表 [`docs/benchmarks/resource-results.md`](https://npmcn.com/package/%40hackylabs/deep-redact/docs/benchmarks/resource-results.md)。 。 。 .

## 配置

`deepRedact(options)` 接受单个选项对象。 所有选项都是可选的.

### 顶级选项

| 选项 | 类型 | 默认 | 需求 | 说明 |
| --- | --- | --- | --- | --- |
| `keys` | `KeySelector[]` | `[]` | 没有 | 编辑任何匹配所列密钥的字段, 任何深度 |
| `paths` | `PathEntry[]` | `[]` | 没有 | 编辑特定路径的字段; 支持精确的字符串、结构化路径、通配符和排除选择器 |
| `stringTests` | `StringTest[]` | `[]` | 没有 | 调整字符串值内的匹配模式 |
| `censor` | `string | function` | `'[REDACTED]'` | 没有 | 替换值或函数 `(value, context) => replacement` |
| `serialise` | `boolean | function` | `false` | 没有 | `true` 返回 JSON 安全字符串; 函数接收安全图表并可能返回任意字符串 |
| `remove` | `boolean` | `false` | 没有 | 从输出中删除匹配的密钥, 而不是替换其值 |
| `retainStructure` | `boolean` | `false` | 没有 | 当父母相匹配时, 保留子孙节点可以用于低优先级规则 |
| `replaceStringByLength` | `boolean` | `false` | 没有 | 重复 `censor` 匹配已编辑值的字符长度的字符串 |
| `types` | `ValueTypeName[]` | `['string']` | 没有 | `typeof` 符合编辑条件的类别; 其数值类型未列出的匹配密钥未受影响 |
| `fuzzyKeyMatch` | `boolean` | `false` | 没有 | 当配置的密钥是字段名的子字符串时匹配(例如. `'pass'` 匹配 `'password'`(中文(简体) ) |
| `caseSensitiveKeyMatch` | `boolean` | `true` | 没有 | 何时 `false`,在比较前将密钥名称(分解非单词字符,小写)正常化 |
| `maxDepth` | `number` | `500` | 没有 | 停止穿越这个筑巢深度; 警戒深筑巢载荷 |
| `maxNodes` | `number` | `50000` | 没有 | 在这么多节点后停止穿行; 防范过大的有效载荷 DoS |
| `onBudgetExceeded` | `'throw' | 'truncate'` | `'throw'` | 没有 | 在一个 `maxDepth`编号 :`maxNodes` 突破, `'throw'` 引起内部预算错误; `'truncate'` 将违法节点替换为 `[TRUNCATED]` 停止, 关闭 |
| `transformers` | `TransformersOption` | 内置默认值 | 没有 | 覆盖运行时间类型在序列化输出中的体现 |
| `diagnostics` | `DiagnosticsOptions` | —— 说 | 没有 | 结构化降解/预算事件 Opt-in sink; 默认沉默( 无控制台输出) 。 过 `getNodeConsoleDiagnosticSink()` 作为 `sink` 登录到控制台 |

`ValueTypeName` 这是: `'string'`, (中文(简体) ), `'number'`, (中文(简体) ), `'bigint'`, (中文(简体) ), `'boolean'`, (中文(简体) ), `'object'`, (中文(简体) ), `'function'`, (中文(简体) ), `'symbol'`, (中文(简体) ), `'undefined'`。 。 。 .

### `KeySelector`

每个条目 `keys` 可能是一个平地 `string`页:1 `RegExp`,或一个 `KeyRule` 每个密钥覆盖的对象.

`keys` 横穿平原对象、阵列、类例本身的可假设字段,以及 `Map`编号 :`Set` 目录. `Map` 条目密钥在结构输出中保留原始密钥对象的同时,与其成型的字符串形式相匹配; `Set` 成员按插入顺序穿行,但其数字位置是路径段而不是合成键.

| 外地 | 类型 | 默认 | 需求 | 说明 |
| --- | --- | --- | --- | --- |
| `key` | `string | RegExp` | —— 说 | 对 | 要匹配的密钥 |
| `censor` | `string | function` | 顶级 `censor` | 没有 | 只覆盖此密钥的审查者 |
| `remove` | `boolean` | 顶级 `remove` | 没有 | 仅为此密钥覆盖删除 |
| `retainStructure` | `boolean` | 顶级 `retainStructure` | 没有 | 仅保留此密钥的构造 |
| `replaceStringByLength` | `boolean` | 顶级 `replaceStringByLength` | 没有 | 仅为此密钥取代 StringByLength |
| `fuzzyKeyMatch` | `boolean` | 顶级 `fuzzyKeyMatch` | 没有 | 仅覆盖此密钥的模糊密钥 |
| `caseSensitiveKeyMatch` | `boolean` | 顶级 `caseSensitiveKeyMatch` | 没有 | 仅覆盖此密钥的敏感KeyMatch |

### `PathEntry`

每个条目 `paths` 可能是平面点注释字符串(如:. `'user.profile.ssn'`),结构化路径数组,或 `PathRule` 用于 per-path 覆盖的对象.

结构化路径数组可能包含:

| 片段类型 | 示例 | 匹配 |
| --- | --- | --- |
| `string` 或者说 `number` | `'password'` | 精确键或索引 |
| `RegExp` | `/^pass/i` | 匹配正则x 的密钥 |
| `{ any: true }` | —— 说 | 任何单一的密钥( E)`*`(中文(简体) ) |
| `{ anyDepth: true }` | —— 说 | 任意深度的零键或多键( N)`**`(中文(简体) ) |
| `{ ignore: string | number | RegExp }` | `{ ignore: 'country' }` | 从周边通配符中排除密钥 |

| 外地 | 类型 | 默认 | 需求 | 说明 |
| --- | --- | --- | --- | --- |
| `path` | `string | PathSegments[]` | —— 说 | 对 | 匹配的路径 |
| `censor` | `string | function` | 顶级 `censor` | 没有 | 仅覆盖此路径的审查者 |
| `remove` | `boolean` | 顶级 `remove` | 没有 | 仅为此路径覆盖删除 |
| `retainStructure` | `boolean` | 顶级 `retainStructure` | 没有 | 覆盖仅保留此路径的构造 |
| `replaceStringByLength` | `boolean` | 顶级 `replaceStringByLength` | 没有 | 仅为此路径取代 StringByLength |

### `StringTest`

每个条目 `stringTests` 也许是赤裸的 `RegExp` (全值替换为 `censor`或一个 `SubstringRule` 用于部分替换.

| 外地 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `pattern` | `RegExp` | 对 | 对照字符串值测试正则表达式 |
| `replacer` | `(value: string, pattern: RegExp) => string` | 对 | 返回已编辑的字符串;仅在 `pattern` 匹配 |

### `TransformersOption`

变形器控制非 JSON 运行时类型在何时被显示 `serialise: true`。每个变压器是一个函数 `(value: unknown) => unknown` ,或者返回已变换的值,或者返回未变换的值以传递给链条中的下一个变压器.

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `byType.bigint` | `Transformer[]` | 适用于 `BigInt` 值( 不查阅) `byType.object`(中文(简体) ) |
| `byType.object` | `Transformer[]` | 首先适用于内置构造器类型和未知对象类型 |
| `byConstructor.Date` | `Transformer[]` | 适用于 `Date` 实例 |
| `byConstructor.Error` | `Transformer[]` | 适用于 `Error` 实例 |
| `byConstructor.Map` | `Transformer[]` | 适用于 `Map` 实例 |
| `byConstructor.RegExp` | `Transformer[]` | 适用于 `RegExp` 实例 |
| `byConstructor.Set` | `Transformer[]` | 适用于 `Set` 实例 |
| `byConstructor.URL` | `Transformer[]` | 适用于 `URL` 实例 |
| `byConstructor.custom` | `CustomConstructorTransformerRegistration[]` | 自定义类型匹配 `instanceof` 按声明顺序排列 |
| `fallback` | `Transformer[]` | 当没有较早的变压器返回已更改的值时应用 |

内置变压器会产生决定性的标记对象(例如. `{ _transformer: 'date', datetime: '<ISO string>' }`) (中文(简体) ). 见 [`docs/architecture/serialise-output.md`](https://npmcn.com/package/%40hackylabs/deep-redact/docs/architecture/serialise-output.md) 用于完整的调度命令和标记形状.

**执行阶段.** 用户 `byConstructor.custom` 财务报告和审定财务报表 `byConstructor.Error` 变压器运行 **在正常转弯之前**,在两种序列模式中:匹配的类实例转换为您返回的平面对象,然后由您擦除 `keys`编号 :`paths` 规则。 这就是PII在类中嵌入的方式——例如: `Error`编号 :`AxiosError` 携带 `config.data` 有效载荷——在没有预先正常步骤的情况下进行编辑(见 [在错误实例中编辑 PII](https://npmcn.com/package/%40hackylabs/deep-redact/docs/examples/custom-error-transformer.md)) (中文(简体) ). 其它水桶(`byType`, (中文(简体) ), `fallback`用户 `byConstructor.{Date,Map,RegExp,Set,URL}`)仅在 `serialise: true` pass; 依赖这种仅序列化的行为——即变压器输出能从编辑中逃脱的行为——是 **已贬值** 支持上面的一等桶.

### `DiagnosticsOptions`

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `sink` | `(event: DiagnosticEvent) => void` | 当一个值退化为 `'[UNSUPPORTED]'` 序列化期间 |

## 公共 API

```ts
import { createRedactor, deepRedact } from '@hackylabs/deep-redact'

// deepRedact and createRedactor are the same factory under different names
const redact = deepRedact({ keys: ['secret'] })
const same = createRedactor({ keys: ['secret'] })
```

## 文档

### 工作实例

-   [关键目标](https://npmcn.com/package/%40hackylabs/deep-redact/docs/examples/key-targeting.md)
-   [模糊和大小写不敏感密钥匹配](https://npmcn.com/package/%40hackylabs/deep-redact/docs/examples/fuzzy-key-matching.md)
-   [路径选择](https://npmcn.com/package/%40hackylabs/deep-redact/docs/examples/path-targeting.md)
-   [通关卡路径段并忽略选择器](https://npmcn.com/package/%40hackylabs/deep-redact/docs/examples/path-segment-ignore.md)
-   [Regex 属性匹配](https://npmcn.com/package/%40hackylabs/deep-redact/docs/examples/regex-property-matching.md)
-   [按键规则覆盖](https://npmcn.com/package/%40hackylabs/deep-redact/docs/examples/per-key-rule-overrides-string.md)
-   [子字符串目标](https://npmcn.com/package/%40hackylabs/deep-redact/docs/examples/substring-targeting.md)
-   [替换和去除](https://npmcn.com/package/%40hackylabs/deep-redact/docs/examples/replacement-and-removal.md)
-   [结构化对序列化输出](https://npmcn.com/package/%40hackylabs/deep-redact/docs/examples/serialised-output.md)
-   [自定义变压器](https://npmcn.com/package/%40hackylabs/deep-redact/docs/examples/custom-transformer.md)
-   [在错误实例中编辑 PII](https://npmcn.com/package/%40hackylabs/deep-redact/docs/examples/custom-error-transformer.md)
-   [值类型允许列表](https://npmcn.com/package/%40hackylabs/deep-redact/docs/examples/value-type-allowlist-default.md)
-   [Singleton / 服务端设置](https://npmcn.com/package/%40hackylabs/deep-redact/docs/examples/singleton-setup.md)
-   [控制台编辑适配器](https://npmcn.com/package/%40hackylabs/deep-redact/docs/examples/console-redaction.md)

### 移徙指南

-   [从 Depen Redact v3 移动](https://npmcn.com/package/%40hackylabs/deep-redact/docs/migration/from-v3.md)
-   [从快速编辑移出](https://npmcn.com/package/%40hackylabs/deep-redact/docs/migration/from-fast-redact.md)

### 建筑和设计

-   [规则优先和评价顺序](https://npmcn.com/package/%40hackylabs/deep-redact/docs/architecture/precedence.md)
-   [串行输出:变压器调度和标记形状](https://npmcn.com/package/%40hackylabs/deep-redact/docs/architecture/serialise-output.md)
-   [单向编辑合同](https://npmcn.com/package/%40hackylabs/deep-redact/docs/architecture/one-way-redaction.md)

### 平台和安全小组

-   [标准化指南](https://npmcn.com/package/%40hackylabs/deep-redact/docs/platform/standardisation-guide.md) 支助能力,针对语义、核查证据和通过决定的范围

## 脚本

-   `pnpm run build`
-   `pnpm run lint`
-   `pnpm run test`
-   `pnpm run generate-exports`
-   `pnpm run generate-readme`
-   `pnpm run verify-generated-files`
-   `pnpm run bench`
-   `pnpm run bench:generate-charts`

## 常见问题

### @hackylabs/deep-redact 是什么？

从对象,阵列和任意字符串\(如XML或原始 cookie 数据\)中深度编辑敏感数据,并具有可相容,函数先的API\.

### 如何安装 @hackylabs/deep-redact？

在项目目录运行 npm install @hackylabs/deep-redact，或使用 pnpm add / yarn add / bun add。

### @hackylabs/deep-redact 支持 TypeScript 吗？

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

### @hackylabs/deep-redact 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @hackylabs/deep-redact 需要什么版本的 Node\.js？

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

### @hackylabs/deep-redact 可以商用吗？

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

### @hackylabs/deep-redact 的下载量有多少？

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

### @hackylabs/deep-redact 还在维护吗？

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

