@adguard/filters-downloader

中文文档

3.0.1发布于 2026/10/30GPL-3.0TypeScriptCommonJS近 30 天下载 8487

下载过滤源文件

文档目录18 节

目录
概览
安装
导入
关键概念
条件常数 DefinedExpressions (中文(简体) )
预处理指令
校验和
差异更新
API 参考
download(url, definedExpressions?, options?)
downloadWithRaw(url, options)
compile(rules, filterOrigin?, definedExpressions?)
resolveConditions(rules, definedExpressions?)
resolveIncludes(rules, filterOrigin?, definedExpressions?)
getFilterUrlOrigin(url)
文档
使用 Filters 下载器的项目

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

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

说明: 此软件包开发于辅助软件Limited/ext-filter-downloader。。。 . 这个护卫小组/拖放器寄存器是一个公共镜像.

概览

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

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

安装

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

导入

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

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

浏览器 (ESM):

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见保护条件指令页:1 完整的识别常数列表.

预处理指令

有条件的块

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

!#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 包含在产出中.

文件包含

!
! 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[]。。。 .

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 所以图书馆可以应用差分补丁来代替全重下载.

// 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下载.

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 参考文献.

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

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

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

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

`getFilterUrlOrigin(url)`

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

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

文档

使用 Filters 下载器的项目

守护浏览器扩展 — AdGuard 浏览器扩展
过滤器编译器 ——从源头编译AdGuard过滤列表
主机列表编译器 ——从多来源编译主机块列表
TSUrlFilter 单簧管 —— 说代理守护符软件包

版本与发布记录

@adguard/filters-downloader 共发布 38 个版本，首次发布于 2021/06/29；过去 12 个月发布了 6 个版本。

版本	发布日期	距今
`3.0.1`latest	2026/10/30	8 天前
`3.0.0`	2026/10/27	11 天前
`3.0.0-beta.0`beta	2026/10/24	15 天前
`2.4.5`	2026/07/14	3 个月前
`2.4.4`	2026/04/14	6 个月前
`2.4.3`	2026/04/04	7 个月前

关于 @adguard/filters-downloader 的常见问题

@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 和提交记录判断。

npm install @adguard/filters-downloader

pnpmpnpm add @adguard/filters-downloader
yarnyarn add @adguard/filters-downloader
bunbun add @adguard/filters-downloader

在你的项目目录中运行此命令。

近 30 天下载

8,487

约 8487 次日均 283 次

统计周期 2026/10/05 – 2026/11/03
数据来自 npm 官方下载统计，2 天前更新

最新版本3.0.1发布于 8 天前

开源许可GPL-3.0强 Copyleft

包体积257 kB15 个文件 · 解压后

运行依赖2 个

模块格式CommonJS

TypeScript自带类型

Node.js^22.21.0 || >=24.0.0

发布版本38 个近 12 个月 6 个

首次发布2021/06/295 年前

元数据更新2026/10/30

每一个软件包背后，
都有分享与创造的人。