# @adguard/filters-downloader 中文文档

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

版本：3\.0\.1
npm 元数据更新时间：2026-10-30T04:50:14.081Z
中文译文更新时间：2026-11-06T00:04:13.278Z
软件包许可：GPL-3\.0

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

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

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

- 包体积（解压后）：257 kB，15 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：^22\.21\.0 \|\| \>=24\.0\.0
- 运行依赖：2 个
- 首次发布：2021-06-29T13:02:27.497Z
- 最新版本发布：2026-10-30T04:50:13.862Z
- 近 30 天下载量：8487（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：38（近 12 个月 6 个）

## 中文简介

下载过滤源文件

## 安装

```sh
npm install @adguard/filters-downloader
```

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

## README

# @ 守护/ 过滤器- 下行装入器

通过解析下载过滤列表源文件的库 预处理指令。 它处理有条件的编译,文件包含, 校验和验证,以及差分(基于patch)过滤器更新。 图书馆 在Node.js和浏览器环境中工作.

> **说明:** 此软件包开发于 [辅助软件Limited/ext-filter-downloader](https://github.com/AdGuardSoftwareLimited/ext-filters-downloader)。 。 。 . 这个 [护卫小组/拖放器](https://github.com/AdguardTeam/FiltersDownloader) 寄存器是一个公共镜像.

## 目录

-   [概览](https://npmcn.com/package/%40adguard/filters-downloader/#readme-overview)
-   [安装](https://npmcn.com/package/%40adguard/filters-downloader/#readme-installation)
    -   [导入](https://npmcn.com/package/%40adguard/filters-downloader/#readme-importing)
-   [关键概念](https://npmcn.com/package/%40adguard/filters-downloader/#readme-key-concepts)
    -   [条件常数](https://npmcn.com/package/%40adguard/filters-downloader/#readme-condition-constants-definedexpressions)
    -   [预处理指令](https://npmcn.com/package/%40adguard/filters-downloader/#readme-preprocessor-directives)
    -   [校验和](https://npmcn.com/package/%40adguard/filters-downloader/#readme-checksums)
    -   [差异更新](https://npmcn.com/package/%40adguard/filters-downloader/#readme-differential-updates)
-   [API 参考](https://npmcn.com/package/%40adguard/filters-downloader/#readme-api-reference)
    -   [`download()`](https://npmcn.com/package/%40adguard/filters-downloader/#readme-downloadurl-definedexpressions-options)
    -   [`downloadWithRaw()`](https://npmcn.com/package/%40adguard/filters-downloader/#readme-downloadwithrawurl-options)
    -   [`compile()`](https://npmcn.com/package/%40adguard/filters-downloader/#readme-compilerules-filterorigin-definedexpressions)
    -   [`resolveConditions()`](https://npmcn.com/package/%40adguard/filters-downloader/#readme-resolveconditionsrules-definedexpressions)
    -   [`resolveIncludes()`](https://npmcn.com/package/%40adguard/filters-downloader/#readme-resolveincludesrules-filterorigin-definedexpressions)
    -   [`getFilterUrlOrigin()`](https://npmcn.com/package/%40adguard/filters-downloader/#readme-getfilterurloriginurl)
-   [文档](https://npmcn.com/package/%40adguard/filters-downloader/#readme-documentation)
-   [使用 Filters 下载器的项目](https://npmcn.com/package/%40adguard/filters-downloader/#readme-projects-using-filtersdownloader)

## 概览

广告屏蔽器使用的过滤列表往往由多个源文件组成 并包含在预处理器指令后加门的平台专用规则. 这个 库取一个过滤器 URL(或一系列规则) 并生成一个平面, 规则清单:

-   **解决 `!#include` 指令** ——获取和内入引用文件
-   **解决 `!#if`编号 :`!#else`编号 :`!#endif` 指令** - 包括或排除规则 基于调用人提供的状态常数的块
-   **验证校验和** ——可选择验证嵌入在其中的MD5校验和 过滤页眉
-   **应用差异更新** - 当一个先前下载的原始过滤器是 ,试图通过二进制补丁而不是完整补丁更新 重新下载

## 安装

```bash
pnpm add @adguard/filters-downloader
# or
npm install @adguard/filters-downloader
# or
yarn add @adguard/filters-downloader
```

### 导入

**节点js(共同JS/无害环境管理):**

```js
import { FiltersDownloader } from '@adguard/filters-downloader';
```

**浏览器 (ESM):**

```js
import { FiltersDownloader } from '@adguard/filters-downloader/browser';
```

## 关键概念

### 条件常数`DefinedExpressions`(中文(简体) )

在编译过滤器时,您会通过 `DefinedExpressions` 声明对象 哪个平台常数 `true` 用于当前广告屏蔽器。 图书馆 评价 `!#if` 针对这些常数的表达式,只包括规则 适用于您的平台.

识别常数:

| 常数 | 说明 |
| --- | --- |
| `adguard` | 担保产品(任何) |
| `adguard_ext_chromium` | 基于铬的浏览器的守护 |
| `adguard_ext_chromium_mv3` | 铬MV3护卫 |
| `adguard_ext_firefox` | Firefox 守护 |
| `adguard_ext_edge` | 边缘护卫 |
| `adguard_ext_safari` | 萨法里守护 |
| `adguard_ext_opera` | 歌剧守护 |
| `adguard_ext_android_cb` | Android 内容屏蔽器的守护 |

任何在 `DefinedExpressions` 对象被视为 `false`见 [保护条件指令](https://adguard.com/kb/general/ad-filtering/create-own-filters/#conditions-directive) 页:1 完整的识别常数列表.

### 预处理指令

#### 有条件的块

```adblock
!#if (adguard && !adguard_ext_safari)
||example.org^$third-party
!#endif
```

```adblock
!#if adguard_ext_firefox
!#include https://example.org/path/firefox-rules.txt
!#else
!#include https://example.org/path/other-rules.txt
!#endif
```

-   `!#if` 编号 : `!#else` 编号 : `!#endif` 划定条件块 .
-   条件支助 `&&`, (中文(简体) ), `||`, (中文(简体) ), `!`括号.
-   只有条件评估为 `true` 包含在产出中.

#### 文件包含

```adblock
!
! Valid (same origin, absolute path):
!#include https://example.org/path/includedfile.txt
!
! Valid (relative path):
!#include /includedfile.txt
!#include ../path2/includedfile.txt
!
! Invalid (different origin — rejected):
!#include https://example.com/path/includedfile.txt
```

`!#include` 获取引用文件,并将其规则切入输出中 那个位置 包含的文件本身可能包含指令. 只有来自 允许与母过滤器相同的来源.

### 校验和

过滤器文件可能会将 MD5 校验和嵌入其头部(例如. `! Checksum: <base64-md5>`) (中文(简体) ). 何时 `validateChecksum: true` 被通过 库在下载后验证校验和。 使用 `validateChecksumStrict: true` 将缺失的校验和视为出错.

### 差异更新

`downloadWithRaw` 将原始(未编译)过滤文本与编译文本一起保存 输出。 在后来的电话中,通过以前存储的 `rawFilter` 让 库应用二进制补丁( 如果服务器提供) 而不是下载 再次使用整个过滤器,减少带宽使用.

对于包含证书的源 URL,库总是下载 完全过滤器。 只有节点.js构建支持这样的URL.

## API 参考

所有方法都已经在 `FiltersDownloader` 对象.

### `download(url, definedExpressions?, options?)`

下载过滤器 `url`,解决所有指令,并返回编译的 规则作为 `string[]`。 。 。 .

```ts
const rules: string[] = await FiltersDownloader.download(
    'https://example.org/filter.txt',
    { adguard: true, adguard_ext_firefox: true },
);
```

**选项** (单位:千美元)`LegacyDownloadOptions`:

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `validateChecksum` | `boolean` | `false` | 校验嵌入式 MD5 校验和 |
| `validateChecksumStrict` | `boolean` | `false` | 如果没有校验和, 错误 |
| `allowEmptyResponse` | `boolean` | `false` | 允许下载空过滤文件 |

默认情况下, 空顶级响应会丢出 `'Response is empty'`包含 不论此选项为何, 文件可能为空 .

* * *

### `downloadWithRaw(url, options)`

下载过滤器并返回编译的规则和原始规则( 未编译) 过滤文本。 在接通电话时,提供存储的 `rawFilter` 所以图书馆 可以应用差分补丁来代替全重下载.

```ts
// First download — no previous raw filter
const { filter, rawFilter } = await FiltersDownloader.downloadWithRaw(
    'https://example.org/filter.txt',
    { definedExpressions: { adguard: true } },
);

// Store rawFilter and use it next time
const { filter: updated, rawFilter: newRaw, isPatchUpdateFailed } =
    await FiltersDownloader.downloadWithRaw(
        'https://example.org/filter.txt',
        {
            rawFilter,           // previously stored raw filter
            definedExpressions: { adguard: true },
        },
    );
```

**回返** (单位:千美元)`DownloadResult`:

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `filter` | `string[]` | 编译规则 |
| `rawFilter` | `string` | 指令解析前的原始过滤文本 |
| `isPatchUpdateFailed` | `boolean | undefined` | `true` 如果一个补丁尝试但失败( 使用完全重新下载代替) |
| `headers` | `object | undefined` | 过滤器下载的 HTTP 响应头(见下文) |

`headers` 形状 :

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `lastModified` | `string | undefined` | 其价值 `Last-Modified` HTTP 响应头 |

> **说明:** `headers.lastModified` 可作为倒置更新时间戳 当过滤器元数据不包含 `TimeUpdated` 字段.

**选项** (单位:千美元)`DownloadWithRawOptions`:

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `force` | `boolean` | `false` | 跳过补丁尝试并强制全部重新下载 |
| `rawFilter` | `string` | `undefined` | 先前存储的原始过滤器 |
| `definedExpressions` | `DefinedExpressions` | `undefined` | 指令解析的条件常数 |
| `validateChecksum` | `boolean` | `false` | 校验嵌入式 MD5 校验和 |
| `validateChecksumStrict` | `boolean` | `false` | 如果没有校验和, 错误 |
| `allowEmptyResponse` | `boolean` | `false` | 允许空过滤器响应 |
| `verbose` | `boolean` | `false` | 启用详细记录以排除出错 |

* * *

### `compile(rules, filterOrigin?, definedExpressions?)`

将所有指令都用已拉近的 `string[]` 规则。 有用时 您有内存中的原始行,不需要HTTP下载.

```ts
const rawRules = [
    '!#if adguard_ext_firefox',
    '||firefox-only.example.org^',
    '!#endif',
    '||example.org^',
];

const compiled: string[] = await FiltersDownloader.compile(
    rawRules,
    'https://example.org/filter.txt', // used to resolve relative !#include paths
    { adguard_ext_firefox: true },
);
// → ['||firefox-only.example.org^', '||example.org^']
```

* * *

### `resolveConditions(rules, definedExpressions?)`

评价 `!#if` 编号 : `!#else` 编号 : `!#endif` 指令并返回新的 `string[]` 并删除了非匹配区块。 对 **没有** 获取 `!#include` 参考文献.

```ts
const filtered = FiltersDownloader.resolveConditions(rules, { adguard: true });
```

* * *

### `resolveIncludes(rules, filterOrigin?, definedExpressions?)`

全部获取并内含 `!#include` 参考文献。 对 **没有** 评价 `!#if` 条件.

```ts
const expanded = await FiltersDownloader.resolveIncludes(
    rules,
    'https://example.org/filter.txt',
    { adguard: true },
);
```

* * *

### `getFilterUrlOrigin(url)`

返回基准目录 URL `url` (每起事件最多包括最后一起) `/`) (中文(简体) ). 内部用于解决相对问题 `!#include` 路径.

```ts
FiltersDownloader.getFilterUrlOrigin('https://example.org/path/filter.txt');
// → 'https://example.org/path'
```

## 文档

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

## 使用 Filters 下载器的项目

-   [守护浏览器扩展](https://github.com/AdguardTeam/AdguardBrowserExtension) — AdGuard 浏览器扩展
-   [过滤器编译器](https://github.com/AdguardTeam/FiltersCompiler) ——从源头编译AdGuard过滤列表
-   [主机列表编译器](https://github.com/AdguardTeam/HostlistCompiler) ——从多来源编译主机块列表
-   [TSUrlFilter 单簧管](https://github.com/AdguardTeam/tsurlfilter) —— 说 [代理守护符](https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/adguard-api) 软件包

## 常见问题

### @adguard/filters-downloader 是什么？

下载过滤源文件

### 如何安装 @adguard/filters-downloader？

在项目目录运行 npm install @adguard/filters-downloader，或使用 pnpm add / yarn add / bun add。

### @adguard/filters-downloader 支持 TypeScript 吗？

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

### @adguard/filters-downloader 支持 ESM 还是 CommonJS？

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

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

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

### @adguard/filters-downloader 可以商用吗？

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

### @adguard/filters-downloader 的下载量有多少？

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

### @adguard/filters-downloader 还在维护吗？

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