# @adguard/dnr-converter 中文文档

规范地址：https://npmcn.com/package/%40adguard/dnr-converter/

版本：2\.0\.0
npm 元数据更新时间：2026-09-29T08:09:03.474Z
中文译文更新时间：2026-11-06T18:04:44.844Z
软件包许可：GPL-3\.0-only

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

原始 npm 页面：https://www.npmjs.com/package/%40adguard/dnr-converter
原文对照：https://npmcn.com/package/%40adguard/dnr-converter/?lang=original
项目主页：https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/dnr-converter#readme
源码仓库：https://github.com/AdGuardSoftwareLimited/ext-tsurlfilter

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

- 包体积（解压后）：3.7 MB，121 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：6 个
- peer 依赖：@adguard/re2-wasm 1\.2\.0
- 首次发布：2026-07-14T18:59:32.311Z
- 最新版本发布：2026-09-29T08:09:03.245Z
- 近 30 天下载量：2514（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

将块状过滤规则转换为与声明网请求(DNR)API相兼容规则的转换器.

## 安装

```sh
npm install @adguard/dnr-converter
```

也可以使用：`pnpm add @adguard/dnr-converter`、`yarn add @adguard/dnr-converter`、`bun add @adguard/dnr-converter`

## README

# DNR 转换器

[![npm-badge](https://img.shields.io/npm/v/@adguard/dnr-converter)](https://www.npmjs.com/package/@adguard/dnr-converter) [![license-badge](https://img.shields.io/npm/l/@adguard/dnr-converter)](https://github.com/AdguardTeam/tsurlfilter/blob/master/packages/dnr-converter/LICENSE)

将块式过滤规则转换成规则的 TypeScript 库 与 Chrome 兼容 [申报网请求(DNR)](https://developer.chrome.com/docs/extensions/reference/api/declarativeNetRequest) API (英语). 它是为开发者设计的 构建需要翻译现有的 AdGuard 浏览器扩展 或其他将过滤列表添加到现代 Chrome 所需的 DNR 格式 扩展.

-   [关键概念](https://npmcn.com/package/%40adguard/dnr-converter/#readme-key-concepts)
    -   [支持的规则类型](https://npmcn.com/package/%40adguard/dnr-converter/#readme-supported-rule-types)
-   [安装](https://npmcn.com/package/%40adguard/dnr-converter/#readme-installation)
    -   [同伴依赖关系](https://npmcn.com/package/%40adguard/dnr-converter/#readme-peer-dependencies)
-   [API 概览](https://npmcn.com/package/%40adguard/dnr-converter/#readme-api-overview)
    -   [`IFilter`](https://npmcn.com/package/%40adguard/dnr-converter/#readme-ifilter)
    -   [`Filter`](https://npmcn.com/package/%40adguard/dnr-converter/#readme-filter)
    -   [`ConverterOptions`](https://npmcn.com/package/%40adguard/dnr-converter/#readme-converteroptions)
    -   [简单流程 : `FilterConverter` + 键 `Ruleset`](https://npmcn.com/package/%40adguard/dnr-converter/#readme-simple-flow-filterconverter--ruleset)
    -   [高级流量 : `FilterConverter` 与 `withSourceMap: true` + 键 `RulesetWithSourceMap`](https://npmcn.com/package/%40adguard/dnr-converter/#readme-advanced-flow-filterconverter-with-withsourcemap-true--rulesetwithsourcemap)
    -   [压缩规则集文件格式](https://npmcn.com/package/%40adguard/dnr-converter/#readme-compact-ruleset-file-format)
    -   [`MetadataRuleset`](https://npmcn.com/package/%40adguard/dnr-converter/#readme-metadataruleset)
    -   [`isSafeRule(rule)`](https://npmcn.com/package/%40adguard/dnr-converter/#readme-issaferulerule)
    -   [`DNR_CONVERTER_VERSION`](https://npmcn.com/package/%40adguard/dnr-converter/#readme-dnr_converter_version)
    -   [网络规则类型](https://npmcn.com/package/%40adguard/dnr-converter/#readme-network-rule-types)
-   [国 际](https://npmcn.com/package/%40adguard/dnr-converter/#readme-cli)
    -   [图标](https://npmcn.com/package/%40adguard/dnr-converter/#readme-commands)
    -   [程序化 API](https://npmcn.com/package/%40adguard/dnr-converter/#readme-programmatic-api)
-   [文档](https://npmcn.com/package/%40adguard/dnr-converter/#readme-documentation)

## 关键概念

-   **过滤器** —— 以对象表示的块状过滤列表 `id` 财务报告和审定财务报表 文本 `content`,每个过滤列表(如AdGuard Base, EasyList)成为一个 `Filter` 输入.
-   **声明规则** a 包括: [`chrome.declarativeNetRequest.Rule`](https://developer.chrome.com/docs/extensions/reference/api/declarativeNetRequest#type-Rule) 浏览器对象 本土评价。 转换器从过滤文本中生成这些.
-   **来源地图** ——从每个产生的宣告规则回溯到它的 初始过滤器和规则索引, 当声明时允许反向查找 规则火灾.
-   **规则安全** -克罗姆 [分类 DNR 规则](https://developer.chrome.com/docs/extensions/reference/api/declarativeNetRequest#safe_rules) 作为 _保险_ (路障,允许, 允许所有请求, 升级计划) 或 _不安全_ (重定向,修改标题). 这个 库显示一个帮助检查安全性的人.
-   **转换器选项** 控制转换输出的限制和路径 (最大规则计数,重定向的资源路径).

### 支持的规则类型

转换器支持几乎所有的块状网络规则修饰. 已知者 MV3限制(声明网请求 API 的固有)为:

**支持的修改符** (带有MV3注释):

-   基本封锁/允许规则, `$third-party`, (中文(简体) ), `$domain` (无正则说明 / `.*` TLDs),所有内容类型(`$script`, (中文(简体) ), `$image`, (中文(简体) ), `$stylesheet`页:1
-   `$important`, (中文(简体) ), `$match-case`, (中文(简体) ), `$method`, (中文(简体) ), `$to`, (中文(简体) ), `$denyallow`, (中文(简体) ), `$header` (无正弦值), `$all`
-   `$redirect` ——不支持允许列表规则
-   `$csp`, (中文(简体) ), `$removeparam`, (中文(简体) ), `$removeheader`, (中文(简体) ), `$permissions` ——许可规则 未支持;条件相同的规则只在 相同的过滤器, 不跨过滤器
-   `$urltransform` ——有限度;复杂变换产生多种声明 通过管道阶段的规则
-   `$cookie` ——有限;只支持无参数(空) `$cookie`(中文(简体) )
-   `$badfilter` - 部分:不处理 `$domain` 正确的相交点

**尚未支持/ 不可转换为 DNR**数字 :

-   `$popup`, (中文(简体) ), `$redirect-rule`, (中文(简体) ), `$referrerpolicy` ——尚未执行
-   `$replace`, (中文(简体) ), `$jsonprune`, (中文(简体) ), `$xmlprune`, (中文(简体) ), `$hls`, (中文(简体) ), `$network`, DNS 修改器(`$client`, (中文(简体) ), `$dnsrewrite`, (中文(简体) ), `$dnstype`, (中文(简体) ), `$ctag`· 不可在国防情报局中表示 转换出错并被跳过
-   例外修改符 `$jsinject`, (中文(简体) ), `$stealth`, (中文(简体) ), `$urlblock`, (中文(简体) ), `$genericblock` —— 说 尚未执行
-   `$webrtc` - 贬值和不支持

关于带有输出的详细转换示例,参见 [转换示例](https://npmcn.com/package/%40adguard/dnr-converter/src/examples/README.md)。 。 。 .

## 安装

```bash
# pnpm
pnpm install @adguard/dnr-converter

# yarn
yarn add @adguard/dnr-converter

# npm
npm install @adguard/dnr-converter
```

### 同伴依赖关系

软件包需要 [`@adguard/re2-wasm`](https://www.npmjs.com/package/@adguard/re2-wasm) (单位:千美元)`1.2.0`)作为regex验证的对等依赖.

## API 概览

图书馆使用单曲 `FilterConverter` 分类 **两种转换模式** 选择 `withSourceMap` 选项 :

|  | 简单模式( 默认) | 高级模式( E)`withSourceMap: true`(中文(简体) ) |
| --- | --- | --- |
| **转换器** | `FilterConverter` | `FilterConverter` |
| **规则** | `Ruleset` (相,内相也 | `RulesetWithSourceMap` (懒散负载,源地图) |
| **输入过滤器** | `IFilter` | `IFilter` |
| **使用大小写** | 当你需要的时候 `DeclarativeRule[]` 从纯过滤文本输出 | 当你需要原始地图时, `$badfilter` 交叉过滤应用程序和序列化 |

### `IFilter`

```ts
import type { IFilter } from '@adguard/dnr-converter';
```

两种转换流所使用的单一接口 :

| 方法 | 类型 | 说明 |
| --- | --- | --- |
| `getId()` | `number` | 唯一过滤器标识符 |
| `getContent()` | `Promise<string>` | 返回过滤器列表的全文 |
| `getRuleByIndex(index)` | `Promise<string>` | 以字符返回规则正文 |
| `unloadContent()` | `void` | 从内存中释放已装入的内容 |

### `Filter`

唯一的混凝土 `IFilter` 由库运出的执行支持两个 构造模式 :

-   **预装** (单位:千美元)`new Filter(id, content: string)`)——接受过滤文本 直接作为字符串. `getContent()` 1. 立即作出决定; `unloadContent()` 是个禁忌 用于简单的转换或当内容已经在内存中时.
    
-   **懒惰** (单位:千美元)`new Filter(id, source: () => Promise<string>)`(b) —— 接受按要求获取内容的自动调用。 支持承诺 双向调用者之间的重复,以及 `unloadContent()` 释放 缓存内容 。 使用方式 `withSourceMap: true` (先进模式).
    

```ts
import { Filter } from '@adguard/dnr-converter';

// Pre-loaded (simple mode)
const filter = new Filter(1, '||example.com^');

// Lazy-loaded (advanced mode with withSourceMap: true)
const lazyFilter = new Filter(1, async () => fetchFilterText());
```

### `ConverterOptions`

```ts
import type { ConverterOptions } from '@adguard/dnr-converter';
```

转换进程的配置 :

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| `resourcesPath` | `string?` | 网络访问资源相对于扩展根的路径( 起始于 `/`没有跟踪 `/`) (中文(简体) ). 所需经费 `$redirect` 规则. |
| `maxNumberOfRules` | `number?` | 最大总申报规则产生。 过度的规则是修剪的. |
| `maxNumberOfUnsafeRules` | `number?` | 允许最大不安全(动态)规则 . |
| `maxNumberOfRegexpRules` | `number?` | 使用最大规则 `regexFilter`。 。 。 . |
| `combine` | `boolean?` | 将所有输入过滤器合并为单一的组合规则集. |
| `withSourceMap` | `boolean?` | 何时 `true`返回 `RulesetWithSourceMap` 改为 `Ruleset`。启用源地图, `$badfilter` 交叉过滤器支持, 和懒惰的加载. |
| `badFilterRules` | `Rule[]?` | 静态 `$badfilter` 扫描时应用的规则( :`withSourceMap: true` 页:1. |

### 简单流程 : `FilterConverter` + 键 `Ruleset`

仅在需要时使用此流量 `DeclarativeRule[]` 从纯过滤器输出 文本,没有源地图或懒惰的加载.

```ts
import { FilterConverter, Filter } from '@adguard/dnr-converter';

const filter = new Filter(1, '||example.com^\n@@||example.com/path^');

const converter = new FilterConverter();
const [{ ruleset, errors, limitations }] = await converter.convert([filter]);

console.log(ruleset.getDeclarativeRules()); // DeclarativeRule[]
console.log(ruleset.getSafeRulesCount());    // 2
console.log(errors.length);                 // 0
```

**将多个过滤器合并为一个规则集 :**

```ts
const [{ ruleset }] = await converter.convert(
    [filter1, filter2],
    { combine: true },
);
// ruleset.getId() === FilterConverter.COMBINED_RULESET_ID
```

**序列化和恢复 :**

```ts
const json = ruleset.serialize();   // JSON string of DeclarativeRule[]

const { Ruleset } = await import('@adguard/dnr-converter');
const restored = Ruleset.deserialize(ruleset.getId(), json);
```

`Ruleset` (默认返回,无) `withSourceMap`() 执行 `IRuleset`数字 :

| 方法 | 回返 | 说明 |
| --- | --- | --- |
| `getId()` | `string` | 规则集标识符(例如. `"ruleset_1"`(中文(简体) ) |
| `getSafeRulesCount()` | `number` | 安全申报规则数(不包括不安全) |
| `getUnsafeRulesCount()` | `number` | 不安全规则数 |
| `getRegexpRulesCount()` | `number` | 基于regexp的规则数 |
| `getDeclarativeRules()` | `DeclarativeRule[]` | 全部转换的 DNR 规则( 同步) |
| `serialize()` | `string` | JSON 声明规则的序列化 |
| `Ruleset.deserialize(id, json)` | `Ruleset` | 静态:从序列化的 JSON 重建 |

### 高级流量 : `FilterConverter` 与 `withSourceMap: true` + 键 `RulesetWithSourceMap`

当您需要源地图时, 在浏览器扩展内部使用此模式 , `$badfilter` 跨过滤器应用程序,有散列地图的序列化,以及懒惰 内容加载。 过 `withSourceMap: true` 选项中 `RulesetWithSourceMap` 结果.

```ts
import { Filter, FilterConverter } from '@adguard/dnr-converter';

const filter = new Filter(1, async () => '||example.com^\n@@||example.com/path^');

const converter = new FilterConverter();
const [{ ruleset, errors }] = await converter.convert([filter], { withSourceMap: true });

const declarativeRules = await ruleset.getDeclarativeRules(); // Promise<DeclarativeRule[]>
const sources = await ruleset.getRulesById(declarativeRules[0].id);
console.log(sources[0].sourceRule); // '||example.com^'
```

**应用 `$badfilter` 从动态过滤器对静态规则集:**

```ts
const [{ ruleset: dynamicRuleset }] = await converter.convert(
    [dynamicFilter],
    { withSourceMap: true },
);
const rulesToDisable = await converter.computeRulesToDisable(
    [dynamicRuleset],
    [staticRuleset],
);
// rulesToDisable: UpdateStaticRulesOptions[]
```

`RulesetWithSourceMap` (返回时) `withSourceMap: true`() 执行 `IRulesetWithSourceMap`数字 :

| 方法 | 回返 | 说明 |
| --- | --- | --- |
| `getId()` | `string` | 规则集标识符 |
| `getSafeRulesCount()` | `number` | 安全申报规则数(不包括不安全) |
| `getUnsafeRulesCount()` | `number` | 不安全规则数 |
| `getRegexpRulesCount()` | `number` | 基于regexp的规则数 |
| `getDeclarativeRules()` | `Promise<DeclarativeRule[]>` | 全部转换为 DNR 规则( 懒惰) |
| `getUnsafeRules()` | `Promise<DeclarativeRule[]>` | 不安全规则子集( 懒惰 ) |
| `getRulesById(id)` | `Promise<SourceRuleAndFilterId[]>` | DNR 规则的来源规则 |
| `getBadFilterRules()` | `NetworkRule[]` | `$badfilter` 本集的规则 |
| `getRulesHashMap()` | `IRulesHashMap` | 快速的散列地图 `$badfilter` 匹配 |
| `getMetadataRulesCount()` | `number` | 规则et文件中的元数据规则,规则集是从(如果不是从文件读取)读取的(如果不是从文件读取) |
| `serializeCompact(unsafeRules, prettyPrint?)` | `Promise<string>` | 规则文件 [紧凑规则文件格式](https://npmcn.com/package/%40adguard/dnr-converter/#readme-compact-ruleset-file-format) |
| `unloadContent()` | `void` | 释放懒惰内容 |
| `RulesetWithSourceMap.fromCompact(id, content, filters)` | `RulesetWithSourceMap` | 构建规则集 `parseCompactRuleset()` 产出 |
| `RulesetWithSourceMap.fromDeserialized(deserialized, metadataRulesCount)` | `RulesetWithSourceMap` | 构建规则集 `RulesetWithSourceMap.deserialize()` 产出 |

```ts
import type { ConversionResult } from '@adguard/dnr-converter';
```

通过转换器方法返回结果 :

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| `ruleset` | `IRuleset` 编号 : `IRulesetWithSourceMap` | 转换的规则集 |
| `errors` | `(ConversionError | Error)[]` | 无法转换的规则 |
| `limitations` | `LimitationError[]` | 超限警告 |
| `declarativeRulesToCancel` | `UpdateStaticRulesOptions[]?` | 静态规则 ID 禁用( 从 `computeRulesToDisable`(中文(简体) ) |

### 压缩规则集文件格式

`serializeCompact()` 财务报告和审定财务报表 `MetadataRuleset.serialize()` 写入 JSON 数组 DNR规则。 数组从一个或多个开始 **元数据规则**: 块规则 谁 `condition.urlFilter` 实值 `dummy.rule.adguard.com` (他们从不匹配) 要求),以及 `metadata` 值为 `{ "chunk": "<fragment>" }`合并 按数组顺序排列的片段给出了序列元数据。 每个 `metadata` 值,包括JSON出逃和包装,最多为65 536 UTF-8 字节: Edge Add-ons 拒绝值较大的软件包. 寻常 申报规则遵循元数据规则.

元数据规则被标记识别 `urlFilter` 一、导 言 `metadata` 键。 主机的转换规则 `dummy.rule.adguard.com` 无 `metadata` 键是一个普通规则.

元数据规则是静态的 DNR 规则:它们数到静态规则 获得规则中任何其他规则没有使用的最小ID. 普通的ID是永远不变的.

```json
[
    { "id": 1, "action": { "type": "block" }, "condition": { "urlFilter": "dummy.rule.adguard.com", "resourceTypes": ["xmlhttprequest"] }, "metadata": { "chunk": "{\"metadata\":{...},\"lazyMetadata\":{...},\"filterCon" } },
    { "id": 2, "action": { "type": "block" }, "condition": { "urlFilter": "dummy.rule.adguard.com", "resourceTypes": ["xmlhttprequest"] }, "metadata": { "chunk": "tent\":\"||example.com^\"}" } },
    { "id": 1234567, "action": { "type": "block" }, "condition": { "urlFilter": "||example.com^" } }
]
```

读取过滤规则集文件 `parseCompactRuleset()`数字 :

```ts
import { Filter, parseCompactRuleset, RulesetWithSourceMap } from '@adguard/dnr-converter';

const content = parseCompactRuleset('ruleset_1', JSON.parse(fileText));
content.metadata;           // SerializedRulesetData
content.lazyMetadata;       // SerializedRulesetLazyData
content.filterContent;      // original filter text
content.declarativeRules;   // ordinary DNR rules, without the metadata rules
content.metadataRulesCount; // number of metadata rules, for static rule quota accounting

// Build the rule set directly from the parsed content.
const ruleset = RulesetWithSourceMap.fromCompact('ruleset_1', content, [new Filter(1, content.filterContent)]);
```

`fromCompact()` 验证 `metadata` 和懒惰的元数据 第一次负载的普通规则, 其计划与 `RulesetWithSourceMap.deserialize()`。规则集保留解析内容 一生的记忆; `unloadContent()` 不释出它.

当这些部件作为字符串存储时, 例如在索引数据库中, 加载它们 懒地与 `deserialize()` 并用 `fromDeserialized()`, (中文(简体) ), 传递存储 `metadataRulesCount`数字 :

```ts
const ruleset = RulesetWithSourceMap.fromDeserialized(
    await RulesetWithSourceMap.deserialize(id, rawData, loadLazyData, loadDeclarativeRules, filters),
    metadataRulesCount,
);
```

读者只接受领先的元数据规则,加入它们 解析一次结果。 它会扔 `InvalidMetadataChunksError` (带有 `rulesetId` 属性),当输入不是数组时,没有导线 元数据规则, 有没有字符串的元数据规则 `chunk`,或当 合并的碎片无效.

### `MetadataRuleset`

```ts
import { MetadataRuleset, METADATA_RULESET_ID } from '@adguard/dnr-converter';
```

用于存储校验和和额外属性的专门规则集 收集 DNR 规则集。 它的序列化在 [紧凑规则文件格式](https://npmcn.com/package/%40adguard/dnr-converter/#readme-compact-ruleset-file-format): JSON 阵列 仅包含元数据规则 `{ checksums, additionalProperties }` 内 `metadata.chunk` 碎片.

`METADATA_RULESET_ID` 是常数 `0`;规则的字符串ID总是 `"ruleset_0"`。 。 。 .

**校验和方法 :**

| 方法 | 回返 | 说明 |
| --- | --- | --- |
| `getId()` | `string` | 永远 `"ruleset_0"` |
| `setChecksum(rulesetId, checksum)` | `void` | 保存规则集的校验和 |
| `getChecksum(rulesetId)` | `string | undefined` | 获取校验和,或 `undefined` 如果没有设置 |
| `getRulesetIds()` | `string[]` | 所有规则设置有校验和的ID |

**额外财产方法:**

| 方法 | 回返 | 说明 |
| --- | --- | --- |
| `setAdditionalProperty(key, value)` | `void` | 存储任意的 JSON 可连锁财产 |
| `getAdditionalProperty(key)` | `unknown | undefined` | 获取财产价值 |
| `hasAdditionalProperty(key)` | `boolean` | 检查属性是否存在 |
| `removeAdditionalProperty(key)` | `void` | 删除一个属性( 如果缺少则不开放) |

**序列化 :**

| 方法 | 回返 | 说明 |
| --- | --- | --- |
| `serialize(pretty?)` | `string` | JSON弦乐团; `pretty=true` 可读输出 |
| `MetadataRuleset.deserialize(json)` | `MetadataRuleset` | 从串行中重建; 抛出 `SyntaxError` 在无效的 JSON 上, `InvalidMetadataChunksError` 错误的元数据规则 错误的有效载荷的验证错误 |

```ts
const meta = new MetadataRuleset();
meta.setChecksum('ruleset_1', 'abc123');
meta.setAdditionalProperty('version', '2.0');

const json = meta.serialize();
const restored = MetadataRuleset.deserialize(json);

console.log(restored.getChecksum('ruleset_1')); // "abc123"
console.log(restored.getAdditionalProperty('version')); // "2.0"
```

### `isSafeRule(rule)`

```ts
import { isSafeRule } from '@adguard/dnr-converter';

// DeclarativeRule from the DNR API
const rule = {
    id: 2,
    priority: 1,
    action: { type: 'block' },
    condition: { urlFilter: 'example.com' },
};

isSafeRule(rule); // true — "block" is a safe action
```

回返 `true` 如果声明规则的行为是 [安全规则行动](https://developer.chrome.com/docs/extensions/reference/api/declarativeNetRequest#safe_rules) (单位:千美元)`block`, (中文(简体) ), `allow`, (中文(简体) ), `allowAllRequests`, (中文(简体) ), `upgradeScheme`) (中文(简体) ). 用于分离安全静态规则 需要额外审查的不安全动态规则.

### `DNR_CONVERTER_VERSION`

```ts
import { DNR_CONVERTER_VERSION } from '@adguard/dnr-converter';

console.log(DNR_CONVERTER_VERSION); // e.g. "0.0.1"
```

带有当前库版本的字符串常数 .

### 网络规则类型

与网络规则解析和验证有关的包输出类型 :

```ts
import {
    Rule,
    HttpHeaderMatcher,
    RuleDeclarativeValidator,
} from '@adguard/dnr-converter';
```

-   **`Rule`** — 解析了域,资源访问器的网络规则 类型、方法、高级修改值、优先级和选项标记. 通过 `Rule.createFromText(filterListId, index, text)`。 。 。 .
-   **`HttpHeaderMatcher`** - 描述解析过的类型 `$header` 修改 数值.
-   **`RuleDeclarativeValidator`** 静态助手,检查是否 `Rule` 可转换为 DNR 规则。 打电话 `RuleDeclarativeValidator.shouldConvertRule(rule)` ——返回 `true` 如果规则是可兑换的, `false` 如果它被悄悄地跳过, 或掷出 `UnsupportedModifierError` 如果规则使用不支持 修饰相.

## 国 际

货包船a `dnr-converter` 用于转换过滤器的命令行工具 列表到 DNR 规则,并从编译的规则中提取过滤器内容.

### 图标

#### `convert`

将元目录中的 AdGuard 过滤列表转换为 DNR 规则 .

```bash
dnr-converter convert \
  ./filters \
  ./resources \
  ./dist/rulesets
```

**参数 :**

| 参数 | 说明 | 默认 |
| --- | --- | --- |
| `<filters_and_metadata_dir>` | 目录包含 `filters.json` 和过滤列表文件 | _(必须)_ |
| `<resources_dir>` | 有重定向资源的目录 | _(必须)_ |
| `[dest_rule_sets_dir]` | 生成的规则输出目录 | `./build/rulesets` |

**选项 :**

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `--debug` | 启用调试日志 | `false` |
| `--prettify-json <bool>` | 漂亮打印 JSON 输出文件 | `true` |
| `--additional-properties <json>` | 在元数据规则中包含作为 JSON 字符串的其他属性 | `{}` |

这个 `filters.json` 元数据文件必须是一系列过滤元数据对象 最少每个 `filterId` 财务报告和审定财务报表 `name` 字段.

#### `extract-filters`

提取嵌入编译的 DNR 规则的原始过滤列表内容 编辑 `convert` 命令.

```bash
dnr-converter extract-filters \
  ./dist/rulesets \
  ./extracted-filters
```

**参数 :**

| 参数 | 说明 |
| --- | --- |
| `<path-to-rulesets>` | 包含已编译规则文件的目录 |
| `<path-to-output>` | 写入已提取过滤文件的目录 |

### 程序化 API

CLI逻辑也可以通过下列程序作为API提供: `@adguard/dnr-converter/cli` 子路径导出 :

```ts
import { convertFilters, generateMD5Hash, type ConvertFiltersOptions } from '@adguard/dnr-converter/cli';

await convertFilters(
    './filters',
    './resources',
    './dist/rulesets',
    { debug: true, prettifyJson: true },
);
```

## 文档

-   [更改日志](https://npmcn.com/package/%40adguard/dnr-converter/CHANGELOG.md)
-   [发展](https://npmcn.com/package/%40adguard/dnr-converter/DEVELOPMENT.md)
-   [从 surlfilter 迁移](https://npmcn.com/package/%40adguard/dnr-converter/MIGRATION.md)
-   [转换示例](https://npmcn.com/package/%40adguard/dnr-converter/src/examples/README.md)
-   [LLM 代理规则](https://npmcn.com/package/%40adguard/dnr-converter/AGENTS.md)

## 常见问题

### @adguard/dnr-converter 是什么？

将块状过滤规则转换为与声明网请求\(DNR\)API相兼容规则的转换器\.

### 如何安装 @adguard/dnr-converter？

在项目目录运行 npm install @adguard/dnr-converter，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@adguard/re2-wasm（1\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 dnr-converter，可以用 npx dnr-converter 直接运行。

### @adguard/dnr-converter 支持 TypeScript 吗？

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

### @adguard/dnr-converter 支持 ESM 还是 CommonJS？

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

### @adguard/dnr-converter 需要什么版本的 Node\.js？

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

### @adguard/dnr-converter 可以商用吗？

@adguard/dnr-converter 使用 GPL-3\.0-only 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以 GPL-3\.0 兼容许可开源，并附带专利与反锁定条款。仅内部使用不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。

### @adguard/dnr-converter 的下载量有多少？

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

### @adguard/dnr-converter 还在维护吗？

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