# @adguard/dnr-rulesets 中文文档

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

版本：5\.0\.20261013160024
npm 元数据更新时间：2026-10-13T16:27:25.212Z
中文译文更新时间：2026-11-05T18:48:17.706Z
软件包许可：GPL-3\.0-only

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

原始 npm 页面：https://www.npmjs.com/package/%40adguard/dnr-rulesets
原文对照：https://npmcn.com/package/%40adguard/dnr-rulesets/?lang=original

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

- 包体积（解压后）：373 MB，185 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：10 个
- 首次发布：2024-06-19T12:40:43.553Z
- 最新版本发布：2026-10-13T16:27:24.993Z
- 近 30 天下载量：55755（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：22205（近 12 个月 16164 个）

## 中文简介

为 mv3 扩展创建 AdGuard DNR 规则的工具

## 安装

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

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

## README

# Dnr 规则集

用于为mv3扩展装入预建的AdGuard DNR规则的功能.

可用的过滤器列表可参见: `filters` 在元数据中:

-   [MV3铬过滤器](https://filters.adtidy.org/extension/chromium-mv3/filters.json), (中文(简体) ),
    
-   [边缘 MV3 过滤器](https://filters.adtidy.org/extension/edge-mv3/filters.json), (中文(简体) ),
    
-   [歌剧院 MV3 过滤器](https://filters.adtidy.org/extension/opera-mv3/filters.json)。 。 。 .
    
-   [Dnr 规则集](https://npmcn.com/package/%40adguard/dnr-rulesets/#readme-dnr-rulesets)
    
    -   [基本用途](https://npmcn.com/package/%40adguard/dnr-rulesets/#readme-basic-usage)
        -   [国 际](https://npmcn.com/package/%40adguard/dnr-rulesets/#readme-cli)
        -   [API 密码](https://npmcn.com/package/%40adguard/dnr-rulesets/#readme-api)
        -   [产出结构](https://npmcn.com/package/%40adguard/dnr-rulesets/#readme-output-structure)
        -   [用户](https://npmcn.com/package/%40adguard/dnr-rulesets/#readme-utils)
            -   [获取版本](https://npmcn.com/package/%40adguard/dnr-rulesets/#readme-getversion)
            -   [获得Version 时间戳](https://npmcn.com/package/%40adguard/dnr-rulesets/#readme-getversiontimestampms)
    -   [高级用途](https://npmcn.com/package/%40adguard/dnr-rulesets/#readme-advanced-usage)
        -   [将规则注入显示对象](https://npmcn.com/package/%40adguard/dnr-rulesets/#readme-injecting-rulesets-to-the-manifest-object)
    -   [示例](https://npmcn.com/package/%40adguard/dnr-rulesets/#readme-example)
    -   [包含过滤列表](https://npmcn.com/package/%40adguard/dnr-rulesets/#readme-included-filter-lists)
    -   [管理 `validator-data.json`](https://npmcn.com/package/%40adguard/dnr-rulesets/#readme-managing-validator-datajson)
        -   [何时更新](https://npmcn.com/package/%40adguard/dnr-rulesets/#readme-when-to-update)
        -   [如何更新](https://npmcn.com/package/%40adguard/dnr-rulesets/#readme-how-to-update)

## 基本用途

安装软件包 .

> 注:要及时更新过滤器,请确保您安装了最新版本的软件包.

```bash
npm install --save-dev @adguard/dnr-rulesets
```

### 国 际

1.  添加脚本到您的 `package.json` 要装入 DNR 规则和补丁扩展列表.

```json
{
    "scripts": {
        "load-dnr-rulesets": "dnr-rulesets load <path-to-output>",
        "patch-manifest": "dnr-rulesets manifest <path-to-manifest> <path-to-filters>"
    }
}
```

可用命令 :

#### `load` 命令

下载并保存 DNR 规则到指定的目录 .

```bash
dnr-rulesets load <path-to-output>
```

**备选方案 `load` 命令 :**

-   `-l, --latest-filters` - 下载最新文本过滤器而不是 DNR 规则( 默认: 假)
-   `-b, --browser <browser>` - 指定可装入过滤器的浏览器 (默认:"铬-mv3"). 可用的浏览器 : `chromium-mv3`, (中文(简体) ), `edge-mv3`, (中文(简体) ), `opera-mv3`。 。 。 .

#### `manifest` 命令

补齐扩展列表以包含 DNR 规则 .

```bash
dnr-rulesets manifest <path-to-manifest> <path-to-filters> [options]
```

**备选方案 `manifest` 命令 :**

-   `-f, --force-update` - 使用已存在的 id 强制更新规则( 默认: 假)
-   `-i, --ids <ids...>` - 过滤 id 到附件, 其他将被忽略( 默认 : \[\] - 附加全部)
-   `-e, --enable <ids...>` - 默认启用过滤器( 默认 : \[\])
-   `-r, --ruleset-prefix <prefix>` - 过滤器 id 前缀( 默认: “ rulesset ”)
-   `-m, --filters-match <match>` - 过滤文件与 glob 模式相匹配( 默认 : “ filter%%% (\[ 0- 9\]) ). txt )

**关于数组选项的说明**: 对于接受多个值的选项(`ids` 财务报告和审定财务报表 `enable`),使用下列语法:

```bash
--ids=1,2
```

#### `watch` 命令

监视过滤文件的更改并重建 DNR 规则.

```bash
dnr-rulesets watch <path-to-manifest> <path-to-resources> [options]
```

**参数 :**

-   `<path-to-manifest>` - 运算表的路径.json文件
-   `<path-to-resources>` - 有资源建立美元直接规则的文件夹 (可通过 `@adguard/tswebextension war` 命令)

**备选方案 `watch` 命令 :**

-   `-p, --path-to-filters` - 过滤器和 i18n 元数据文件路径( 默认 ): `./filters` 相对于显示文件夹)
-   `-o, --output-path-for-rulesets` - 规则的输出路径 (默认 : `./filters/declarative` 相对于显示文件夹)
-   `-f, --force-update` - 使用已存在的 id (默认: true) 强制更新规则
-   `-i, --ids <ids...>` - 过滤 id 处理, 其他将被忽略 (默认 : \[\] - 处理所有匹配的过滤器 `--filters-match`(中文(简体) )
-   `-e, --enable <ids...>` - 默认情况下在表单中启用过滤器。json(默认:\[\])
-   `-r, --ruleset-prefix <prefix>` - 过滤器 id 前缀( 默认: “ rulesset ”)
-   `-m, --filters-match <match>` - 过滤文件与 glob 模式相匹配( 默认 : “ filter%%% (\[ 0- 9\]) ). txt )
-   `-l, --latest-filters` - 在表前第一个开始下载最新文本过滤器( 默认: 虚假)
-   `-b, --browser <browser>` - 指定下载最新过滤器的浏览器 (默认:"铬-mv3"). 见 `--latest-filters` 选项. 可用的浏览器 : `chromium-mv3`, (中文(简体) ), `edge-mv3`, (中文(简体) ), `opera-mv3`。 。 。 .
-   `-d, --debug` - 在转换时允许扩展记录( 默认: 假)
-   `-j, --prettify-json` - 预设 JSON 输出( 默认: 真)

### `exclude-unsafe-rules` 命令

在指定的目录中扫描规则, 排除不安全的规则,并保存 排除元数据文件中不安全的规则,并更新规则检查和.

```bash
dnr-rulesets exclude-unsafe-rules <dir> [options]
```

**参数 :**

-   `<dir>`: 包含要处理的规则的文件夹路径.

**选项 :**

-   `-j, --prettify-json <bool>`: 保护 JSON 输出(`true` 或者说 `false`,默认值 : `true`(中文(简体) )
-   `-l, --limit <number>`: 限制不安全规则的数量以排除. 如果不安全规则的数量超过这个限制, 命令会显示错误.

**示例**

```bash
dnr-rulesets exclude-unsafe-rules ./filters/declarative --prettify-json false --limit 100
```

**关于数组选项的说明**: 对于接受多个值的选项(`ids` 财务报告和审定财务报表 `enable`),使用下列语法:

```bash
--ids=1,2
```

1.  运行脚本以装入 DNR 规则作为构建流程的一部分 .

```bash
npm run load-dnr-rulesets
```

1.  补齐您的扩展列表以包含 DNR 规则 .

```bash
npm run patch-manifest
```

### API 密码

您也可以将下载和更新运算表的功能整合到您的构建脚本中:

1.  装入 DNR 规则 .
    
    这种方法将预建资产复制到指定的输出目录,包括:
    
    -   用于所有可用过滤器的 JSON 格式的 DNR 规则
    -   `filters_i18n.json` - 带有过滤名称和描述的翻译文件
    -   `local_script_rules.js` - JS模块格式的本地脚本规则文件 高度建议提供 本地脚本规则 。 如果在构建过程中没有提供, 所有脚本规则 (脚本除外)不会被注入以确保遵守 Chrome Web Store 政策.
    -   `local_script_rules.json` - JSON格式的本地脚本规则 标注 v2. 如果不提供,所有脚本规则都按允许的处理. 应根据其政策在Firefox AMO中提供.
    
    ```ts
    import { AssetsLoader, BrowserFilters } from '@adguard/dnr-rulesets';
    
    const loader = new AssetsLoader();
    await loader.load('<path-to-output>', options);
    ```
    
    地点 `options` 为具有下列属性的对象:
    
    ```ts
    export type AssetsLoaderOptions = {
        /**
         * Whether to download latest text filters instead of DNR rulesets.
        */
        latestFilters?: boolean;
    
        /**
         * For which browser load assets for.
        * Default value: `BrowserFilters.ChromiumMV3`.
        */
        browser?: BrowserFilters;
    };
    ```
    

````
To copy only the `declarative/` rulesets directory (skipping
`filters_i18n.json`, `local_script_rules.js`, etc.), pass the
`onlyDeclarativeRulesets` option. This is useful for Chrome Web Store
extensions that rely on the
[skip review](https://developer.chrome.com/docs/webstore/skip-review)
mechanism, which requires that only `rule_resources` files are changed:

```ts
await loader.load('<path-to-output>', { onlyDeclarativeRulesets: true });
```

To copy only the `declarative/` rulesets directory (skipping
`filters_i18n.json`, `local_script_rules.js`, etc.), pass the
`onlyDeclarativeRulesets` option. This is useful for Chrome Web Store
extensions that rely on the
[skip review](https://developer.chrome.com/docs/webstore/skip-review)
mechanism, which requires that only `rule_resources` files are changed:

```ts
await loader.load('<path-to-output>', { onlyDeclarativeRulesets: true });
```
````

2.  只复制本地脚本规则 .
    
    **选项A:复制 JavaScript 格式规则**
    
    ```ts
    import { AssetsLoader, BrowserFilters } from '@adguard/dnr-rulesets';
    
    const loader = new AssetsLoader();
    await loader.copyLocalScriptRulesJs('<path-to-output>', BrowserFilters.ChromiumMv3);
    ```
    
    此方法只复制 `local_script_rules.js` 文件到指定的目的目录.
    
    **备选案文B:复制JSON格式规则**
    
    ```ts
    import { AssetsLoader, BrowserFilters } from '@adguard/dnr-rulesets';
    
    const loader = new AssetsLoader();
    await loader.copyLocalScriptRulesJson('<path-to-output>', BrowserFilters.ChromiumMv3);
    ```
    
    此方法只复制 `local_script_rules.json` 文件到指定的目的目录.
    
3.  以自定义规则扩展本地脚本规则 .
    
    **备选案文A:使用 `extendLocalScriptRulesJs`** (主要V3级)
    
    ```ts
    import { AssetsLoader } from '@adguard/dnr-rulesets';
    
    const loader = new AssetsLoader();
    await loader.extendLocalScriptRulesJs(
        '<path-to-local-script-rules.js>',
        [
            'example.com#%#const ad = document.querySelector(".ad"); ad.remove();',
            'example.org#%#console.log("Custom script");'
        ]
    );
    ```
    

````
This method parses custom filtering rules, extracts JavaScript
injection rules from them, and appends them to an existing
`local_script_rules.js` file. It's useful for dynamically adding
custom JS rules to your extension at build time.

**Option B: Using `extendLocalScriptRulesJson`** (Manifest V2)

```ts
import { AssetsLoader } from '@adguard/dnr-rulesets';

const loader = new AssetsLoader();
await loader.extendLocalScriptRulesJson(
    '<path-to-local-script-rules.json>',
    [
        'example.com#%#const ad = document.querySelector(".ad"); ad.remove();',
        'example.org,~sub.example.org#%#console.log("Custom script");'
    ]
);
```

This method parses custom filtering rules, extracts JavaScript
injection rules with their domain configurations (both permitted and
restricted domains), and merges them into an existing
`local_script_rules.json` file. Use this method when you need to
maintain domain-specific rule associations.

> **Note:** The `extendLocalScriptRulesJs` and
> `extendLocalScriptRulesJson` methods are only available in the
> programmatic API and not in the CLI. These methods require
> programmatic access to parse and manipulate existing local script
> rule files, which is more suitable for build scripts and custom
> automation workflows rather than command-line usage.
````

4.  补丁扩展列表 .
    
    ```ts
    import { ManifestPatcher } from '@adguard/dnr-rulesets';
    
    const patcher = new ManifestPatcher();
    
    patcher.patch(
        '<path-to-manifest>',
        '<path-to-filters>',
        {
            // Optional: specify filter IDs to include
            ids: ['2', '3'],
            // Optional: specify enabled filter IDs
            enabled: ['2'],
            // Optional: set to true to overwrite existing rulesets
            forceUpdate: true,
            // Optional: set prefix for ruleset paths
            rulesetPrefix: 'ruleset_',
            // Optional: specify filter files matching glob pattern
            filtersMatch: 'filter_+([0-9]).txt',
        },
    )
    ```
    

你也可以打电话 `excludeUnsafeRules` 在自定义中构建流程或自动化脚本.

```ts
import { excludeUnsafeRules } from '@adguard/dnr-rulesets';

await excludeUnsafeRules('<path-to-rulesets-dir>', {
    prettifyJson: true, // optional
    limit: 100,         // optional
});
```

### 产出结构

```bash
/
    |
    |filters
        |
        |<browser>
            |
            |declarative
            |   |
            |   |ruleset_0
            |   |   |
            |   |   |ruleset_0.json # This is special ruleset which stores metadata about all other rulesets
            |   |
            |   |ruleset_<id>
            |       |
            |       |ruleset_<id>.json # DNR ruleset converted from filter_<id>.txt
            |
            |filter_i18n.json # i18n metadata (name, description, etc.) for filters
```

何处 `<browser>` 是构建规则的浏览器,例如. `chromium-mv3`, (中文(简体) ), `edge-mv3` 或者说 `opera-mv3`。 。 。 .

### 用户

该软件包为DNR规则的工作提供了一套实用功能.

#### `getVersion()`

返回软件包的版本.

```ts
import { getVersion } from '@adguard/dnr-rulesets/utils';

const dnrRulesetsVersion = getVersion();
```

#### `getVersionTimestampMs()`

返回基于补丁版本的 dnr 规则集构建的时间戳, 如果补丁版本中没有日期和时间,则或函数调用当前时间戳.

```ts
import { getVersionTimestampMs } from '@adguard/dnr-rulesets/utils';

const dnrRulesetsBuildTimestamp = getVersionTimestampMs();
```

## 高级用途

### 将规则注入显示对象

我们还提供灵活的API,对显示对象适用规则. 如果您想在捆绑时补齐标本, 这会很有用 .

```ts
import { RulesetsInjector } from '@adguard/dnr-rulesets';

const injector = new RulesetsInjector();

const manifest = {
    // Your manifest data
};

const ManifestWithRulesets = injector.applyRulesets(
    (id) => `<path to rulesets>/${id}.json`,
    manifest,
    ['2', '3'],
    {
        // Optional: specify filter IDs to include
        ids: ['2', '3'],
        // Optional: specify enabled filter IDs
        enabled: ['2'],
        // Optional: set to true to overwrite existing rulesets
        forceUpdate: true,
        // Optional: set prefix for ruleset paths
        rulesetPrefix: 'ruleset_',
    },
);
```

## 示例

使用实例: [备注- api- mv3](https://npmcn.com/package/%40adguard/examples/adguard-api-mv3)

## 包含过滤列表

见包含过滤器的列表 [档案员(md)](https://npmcn.com/package/%40adguard/dnr-rulesets/FILTERS.md)。 。 。 .

## 管理 `validator-data.json`

文件 `tasks/validator-data.json` 有两个目的:

1.  **建设后验证** (单位:千美元)`pnpm validate:assets`:经过一个建筑 校验器将新生成的规则ID和元数据密钥与 这个文件。 如果两者不同, 构建失败, 错误请求更新 文件和更改日志.
    
2.  **预建许可列表** (自动建设):当环境变量 `DNR_FILTER_KNOWN_ONLY=true` 设置(在 Docker/CI 自动构建中用于 稳定分支),只有此文件中列出的过滤器ID被下载. 防止过滤器中新添加的过滤器漏入 更古老的稳定建筑.
    

### 何时更新

更新 `validator-data.json` 当过滤器是 **添加或删除** 用于支持浏览器的注册。 典型情景:

-   在 FiltersRegistry 中发布新的过滤器 .
-   已存在的过滤器被移除或其ID更改 .

### 如何更新

1.  运行一个完整的构建以下载最新的过滤器并生成规则 :
    
    ```bash
    pnpm build:assets
    ```
    
2.  运行验证——它将失败并打印添加/删除的规则集ID:
    
    ```bash
    pnpm validate:assets
    ```
    
3.  更新 `tasks/validator-data.json` 与新数据。 最简单的办法是 将构建中的输出复制到文件, 保留 JSON 结构 包含每个浏览器条目(`chromium-mv3`, (中文(简体) ), `edge-mv3`, (中文(简体) ), `opera-mv3`),每个 包含 `version`, (中文(简体) ), `rulesetIds`,以及 `rulesetMetadataKeys`。 。 。 .
    
4.  弹出软件包版本——至少 **小声** 版本,不仅仅是 补丁。 过滤列表版本基于时间戳(例如. `4.2.20260617150056`),所以是补丁起伏(例如. `4.2.3`这将是 semver - 不及当前稳定过滤列表版本。 弹出 小版本(例如:. `4.3.0`)确保软件包版本保持更大 比任何过滤列表版本。 然后更新更改日志.
    
5.  提交更新 `validator-data.json` 与版本起伏.
    

## 文档

-   [更改日志](https://npmcn.com/package/%40adguard/dnr-rulesets/CHANGELOG.md)
-   [发展指南](https://npmcn.com/package/DEVELOPMENT.md)
-   [LLM 代理规则](https://npmcn.com/package/%40adguard/dnr-rulesets/AGENTS.md)

## 常见问题

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

为 mv3 扩展创建 AdGuard DNR 规则的工具

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

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

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

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

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

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

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

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

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

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

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

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