# @eyeo/webext-ad-filtering-solution 中文文档 规范地址：https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/ 版本：5\.0\.0 npm 元数据更新时间：2026-11-13T14:34:12.598Z 中文译文更新时间：2026-11-14T06:33:46.885Z 软件包许可：GPL-3\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40eyeo/webext-ad-filtering-solution 原文对照：https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/?lang=original 项目主页：https://gitlab.com/eyeo/browser-extensions-and-premium/extensions/extensions#readme 源码仓库：https://gitlab.com/eyeo/browser-extensions-and-premium/extensions/extensions ## 关键信息（来自 npm 元数据） - 包体积（解压后）：9.2 MB，111 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：9 个 - peer 依赖：mocha 10\.8\.2，webextension-polyfill \* - 首次发布：2023-09-21T09:56:12.241Z - 最新版本发布：2026-11-13T14:34:12.330Z - 近 30 天下载量：4048（2026-10-14 至 2026-11-12，npm 官方下载统计） - 已发布版本数：47（近 12 个月 7 个） ## 中文简介 iyo 的 Web 扩展辅助过滤解决方案 ## 安装 ```sh npm install @eyeo/webext-ad-filtering-solution ``` 也可以使用：`pnpm add @eyeo/webext-ad-filtering-solution`、`yarn add @eyeo/webext-ad-filtering-solution`、`bun add @eyeo/webext-ad-filtering-solution` ## README # iyo 的 Web 扩展辅助过滤解决方案 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/CODE_OF_CONDUCT.md) 这是一个图书馆,提供集成 eyo's Ad Blocking Core 用于铬和Firefox扩展(如 [附加障碍](https://gitlab.com/adblockinc/ext/adblockplus/adblockplusui)) (中文(简体) ). 广告 封锁核心在 `adblockpluscore` 目录。 见该目录的内容 以供参考. ## 目录 - [行为守则](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-code-of-conduct) - [目录结构](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-directory-structure) - [开始](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-getting-started) - [支持的浏览器](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-supported-browsers) - [V2声明](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-manifest-for-v2) - [V3声明](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-manifest-for-v3) - [需要的许可和为什么我们需要这些许可](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-required-permissions-and-why-we-need-them) - [API 密码](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-api) - [模块捆绑器( 可选)](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-module-bundlers-optional) - [片段过滤支持](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-snippet-filters-support) - [共有资源](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-shared-resources) - [通知支持](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-notifications-support) - [一个点击允许列表支持](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-one-click-allowlisting-support) - [类型脚本](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-typescript) - [文档](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-documentation) - [发展](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-development) - [先决条件](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-prerequisites) - [安装/更新依赖关系](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-installingupdating-dependencies) - [建设图书馆](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-building-the-library) - [编制文件](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-building-the-documentation) - [打开密码](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-linting-the-code) - [测试](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-testing) - [出版](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-publishing) - [活动](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-events) - [支持宣言V3](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/#readme-manifest-v3) ## 行为守则 这个项目的所有捐助者都必须阅读并跟踪我们 [行为守则](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/CODE_OF_CONDUCT.md)。 。 。 . ## 目录结构 ``` core/sdk/ ├── adblockpluscore/ # adblockpluscore ad-filtering engine ├── docs/ # Documentation ├── dist/ # SDK distribution files ├── scripts/ # Build scripts and tooling ├── src/ # SDK Source code │ ├── all/ (or shared/) # Code for any execution context │ ├── background/ # Code for background process │ ├── content/ # Code for isolated world │ ├── front/ # Code for UI page and isolated world │ └── main/ # Code for main world └── test/ # Functional tests ``` SDK源代码由 [执行上下文](https://npmcn.com/package/README.md#extension-execution-contexts)。 。 。 . ## 开始 图书馆分为四个部分: - `ewe-api.js` 包含在扩展的背景页面中 - `ewe-content.js` 要装入为内容脚本( 孤立世界) - `ewe-content-main.js` 要装入为内容脚本( 主世界) - `ewe-content-api.js` 将导入扩展名的各种内容脚本 - `ewe-ui.js` 要装入扩展名的各种UI页面 你可以从 [无](https://www.npmjs.com/package/@eyeo/webext-ad-filtering-solution)。 。 。 . 此外,SDK还提供独立的公用事业,在这两个部门都能够工作 浏览器扩展上下文,以及其他Javascript上下文. 有了两个版本的API,《宣言V2》和《宣言V3》 您需要两个不同的列表, 取决于您的 API 目标. ### 支持的浏览器 网外过滤解决方案(作为短期,我们使用“引擎”) 以下版本: 宣言五2: - 127和最新铬 - Firefox 128 和最新版本 - 最近的边缘 Chromium 129和较新的不支持MV2网络扩展,因此版本为"128.06613.0" 用于MV2测试. 外观V3: - 127和最新铬 - 最近的边缘 - Safari 最新- iOS 和 macOS( 有限支持) 由扩展和 Webext 支持的浏览器列表可见于 [支持的浏览器](https://npmcn.com/package/README.md#supported-browsers)。 。 。 . ### V2声明 对于"宣言"V2,扩展 `manifest.json` 要求 包括下列配置: ``` { "manifest_version": 2, "background": { "scripts": [ "ewe-api.js" ] }, "content_scripts": [ { "all_frames": true, "js": [ "ewe-content.js" ], "match_about_blank": true, "matches": [ "http://*/*", "https://*/*" ], "run_at": "document_start" } ], "permissions": [ "webNavigation", "webRequest", "webRequestBlocking", "scripting", "storage", "unlimitedStorage", "tabs", "" ] } ``` ### V3声明 对于表V3,扩展 `manifest.json` 要求 包括下列配置: ``` { "manifest_version": 3, "background": { "service_worker": "background.js" }, "content_scripts": [ { "all_frames": true, "js": [ "ewe-content.js" ], "match_about_blank": true, "matches": [ "http://*/*", "https://*/*" ], "run_at": "document_start" } ], "permissions": [ "declarativeNetRequest", "scripting", "storage", "tabs", "webNavigation", "webRequest", "unlimitedStorage" ], "host_permissions": [ "" ], "declarative_net_request": } ``` 上面的例子需要几处修改,不能使用 现为. 这个 `service_worker` 需要将值设置为您构建的文件 背景脚本,包括 `ewe-api.js`。 。 。 . 请注意,对于上面的样本,你需要确保设置 数值 `declarative_net_request` 适当的时候, [显示于 解析网 文档](https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#manifest)。 。 。 . 这意味着您还需要在扩展名中添加包含 本节中声明的规则以及文本过滤列表。 参考 改为 [宣言V3文件](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/docs/MANIFEST_V3.md) 更多细节. 许可 `declarativeNetRequestWithHostAccess` 要求 `host_permissions` 将会是 ``。你可以使用 `declarativeNetRequest` 允许不设置 `host_permissions`但它将起到防止 过滤内容并限制网络请求的屏蔽 中指明的 `host_permissions`默认配置 提供的功能最多. ### 需要的许可和为什么我们需要这些许可 WebExt 自动过滤解决方案需要多个权限才能运行 对 上面的表单文件模板包括所需的权限. 这就是为什么我们需要每个: - `webNavigation`: 允许访问 Web 导航 API, 我们使用它 应用文档级别允许过滤并屏蔽弹出. - `webRequest`: 给予访问网络请求 API. 用于应用 URL 过滤器 在MV2中,并在MV3中报告URL过滤器. 也用来取回站点密钥 为网站. - `webRequestBlocking` (仅MV2):允许基于 URL 过滤器的屏蔽请求 在MV2中进行. - `declarativeNetRequest` (仅MV3):允许访问声明网 请求API,我们使用它来应用MV3中的URL过滤器. - `storage`: 允许访问存储的 API, 我们用来存储下载的 API 订阅,用户自定义过滤器等. - `unlimitedStorage`:默认情况下,只允许扩展存储 5MB, 这还不足以让更多的人订阅 此权限可以删除 限制. - `tabs`: 允许访问一些标签元数据, 包括标签的 URL, 即 用于在标签上应用允许过滤的文档级别. - `scripting`: (仅限MV3和Firefox MV2). 曾经应用内容过滤器, 包括元素隐藏过滤器和片段过滤器. - ``:允许WebExt Ad-Filtering解决方案在所有网站上采取行动. 请注意,在MV2中,这表现在 `permissions`,但在MV3 说明这是新的 `host_permissions` 节. 浏览器扩展权限及其效果 谷歌的文档为 [MV2 权限](https://developer.chrome.com/docs/extensions/mv2/declare_permissions/) 财务报告和审定财务报表 [MV3 权限](https://developer.chrome.com/docs/extensions/mv3/declare_permissions/) ### API 密码 API 将以您自己的背景脚本和UI 页面通过 全球 `EWE` 对象。 在背景脚本中,请拨打 `EWE.start()` 开始屏蔽广告. 至少需要将下列信息传递给 `EWE.start()`数字 : - `bundledSubscriptions` (仅限 Express v3) 可在 `bundledSubscriptionsPath` - `bundledSubscriptionsPath` (仅限 Express v3) 包含 ABP- syntax 过滤器列表的扩展构建中的目录路径 文件 _例如/数据/规则/附录_ - `heavyDependenciesPath` 扩展架构中 dist/ewe- heavy-dependency.js 文件的路径 _例如,/vendor/@yeo/webext-ad-filtering-solution/havy-dependenies.js_ 注意在MV3扩展中, `EWE.start()` 必须在第一个 服务员事件循环的转弯,以便它能够附加 事件听众. ### 模块捆绑器( 可选) `ewe-api.js` 财务报告和审定财务报表 `ewe-ui.js` 作为UMD模块构建(Universal模块) 定义),并因此也可以与模块捆绑器一起使用. 如果对背景脚本使用模块捆绑器, **别** 添加 `ewe-api.js` 给您的 `manifest.json`。类似地,如果对脚本使用模块捆绑器 UI页面, **别** 添加 `ewe-ui.js` 到你的UI页面. 因此,不会有一个全球 `EWE` 对象. #### 常见JS ``` const EWE = require("@eyeo/webext-ad-filtering-solution"); EWE.start(addonInfo); ``` #### 无害环境管理 ``` import * as EWE from "@eyeo/webext-ad-filtering-solution"; EWE.start(addonInfo); ``` 也可以导入内容脚本. 这只应包括一次 扩展名,因为它开始运行内容脚本而无需调用 任何一种"启动"功能. ``` import "@eyeo/webext-ad-filtering-solution/content"; ``` 任何情况下都可以使用的个别公用事业也可以进口. ``` import {Scheduler} from "@eyeo/webext-ad-filtering-solution/all/scheduler.js"; ``` 用于在UI背景下运行的功能性(流行、选项等) 将使用 `ewe-ui.js` 文档。 可通过下列方式导入到这些页面: 使用ui页中的以下机制: ``` import * as EWE from "@eyeo/webext-ad-filtering-solution/ui"; ``` 或直接处理捆绑和导入生成的文件: ``` ``` 在内容脚本上下文运行的功能性 将使用 `ewe-content-api.js` 文档。 此选项可通过 使用下列机制: ``` import * as EWE from "@eyeo/webext-ad-filtering-solution/content-api"; ``` ### 片段过滤支持 这个 [片段库](https://gitlab.com/eyeo/adblockplus/abp-snippets) 默认可用 `EWE`。 。 。 . 查阅文件 [片段过滤器](https://help.eyeo.com/adblockplus/snippet-filters-tutorial) 学会如何学习 使用它们. ### 共有资源 有一些共享资源被两个Webext-ad-filtering-Solution使用 生产代码( p) : - `browser` - 全局由网络扩展-多填充版本0.8.0. - `browser.runtime.connect()`编号 :`browser.runtime.onConnect` - 频道名前缀为"ewe:". - `browser.runtime.sendMessage()`编号 :`browser.runtime.onMessage` - 我们的信息是带有“类型”属性的对象,其值前缀为 "我们:". - `indexedDB.open()` - 数据库名称以"EWE"为前缀. - 网页链接 - 模块使用的链接被前缀为"abp:"或"https://subcritic.adblockplus.org/". - `browser.storage.local` 财务报告和审定财务报表 `browser.storage.session` - 存储密钥前缀有"ewe:"或"abp:pref:". 在初始化期间,引擎将遗留数据从 本地存储为索引DB。 迁移的文件必须前缀 : `file:`。 。 。 . 前缀的文件 `file:///` 将被忽略. ### 通知支持 使用 [通知模块](https://eyeo.gitlab.io/browser-extensions-and-premium/extensions/extensions/sdk/#notifications) 是可选的。 开始 用它,需要初始化: ``` EWE.notifications.start(); ``` ### 一个点击允许列表支持 要启用一次点击允许列表, 您需要设置列表 授权用于认证允许列名的公共密钥 请求. ``` EWE.allowlisting.setAuthorizedKeys(keys); ``` 见 [允许列表模块](https://eyeo.gitlab.io/browser-extensions-and-premium/extensions/extensions/sdk/#allowlisting) 更多文件 细节. 通过正确的算法和设置可以创建新的密钥页 使用我们的键盘页创建脚本. ``` npm run -w @eyeo/webext-ad-filtering-solution create-allowlisting-keypair ``` 关于我们剧本的运行详情,见下文开发部分 以及其他EWE开发任务. 键也可以使用 其他程序如OpenSSL. 密钥使用 RSASSA- PKCS1- v1 5 算法,SHA512散列和4096位长模. 此外,何时 转至 `setAuthorizedKeys`,键应当为 base64 编码 字符串,使用 SPKI 格式. ### 类型脚本 类型声明目前手动生成,位于 `/src/types/index.d.ts` 文档. 请确保每次要创建或更新类型时都会更新此文件 . ## 文档 详情请查阅 [API 文档](https://eyeo.gitlab.io/browser-extensions-and-premium/extensions/extensions/sdk/#apis)。 。 。 . ## 发展 ### 先决条件 - 节点 18.16 - npm 第9页 ### 安装/更新依赖关系 ``` npm install ``` ### 建设图书馆 ``` npm run build -- --scope @eyeo/webext-ad-filtering-solution ``` ### 本地运行( 并监视变化) ``` cd core/sdk/ npx webpack --watch ``` #### 自定义构建 我们的构建脚本是一个 CLI 程序, 并带有一些额外的旗帜, 可以 被传给它。 如果您需要, 它可以列出可用的选项 `--help`。 。 。 . ``` npm run build -- --scope @eyeo/webext-ad-filtering-solution -- --help ``` 有一些特定的旗帜也许可以用来定制 构建 : ``` # Build only engine, no test extensions npm run build -- --scope @eyeo/webext-ad-filtering-solution -- --config-name engine # Don't generate any sourcemaps npm run build -- --scope @eyeo/webext-ad-filtering-solution -- --no-devtool ``` 在背景中,这个脚本正在使用Webpack. 你也可以看到 [webpack 命令行选项](https://webpack.js.org/api/cli/) 页:1 关于这些旗帜的进一步资料. ##### 管理测试楼的包装订阅 在MV3扩展(和MV3测试扩展)中,订阅是: 固定在建设时间 捆绑的订阅基于 打开 [定制订阅 文件](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/test/scripts/custom-subscriptions.json)组合 如果文件更改, 订阅由构建脚本更新 . 工作时需要注意的个案 测试是,如果订阅的过滤器有 已更改。 如果您需要调整新过滤器和列表 订阅没有改变,你可以使用 `--force-subscription-update` 旗到构建脚本. ``` npm run build -- --scope @eyeo/webext-ad-filtering-solution -- --force-subscription-update ``` ##### 使用自己的测试服务器实例 默认情况下,构建脚本将启动测试服务器 更新捆绑的订阅。 如果您喜欢使用测试服务器 ,您可以使用 `--use-external-server` 旗帜. ``` npm run -w @eyeo/test-utils start-sdk-server & npm run build -- --scope @eyeo/webext-ad-filtering-solution -- --use-external-server ``` #### 发行构建 默认情况下,调试构建会被创建. 如果构建要使用的库 在另一个项目中,您想要创建一个释放构建. ``` npm run build:release -- --scope @eyeo/webext-ad-filtering-solution ``` ### 编制文件 ``` npm run -w @eyeo/webext-ad-filtering-solution docs ``` ### 打开密码 林廷从"独取"之根而出. ``` npm run lint ``` ## 测试 关于测试的全部文件,请参见我们 [测试文档](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/docs/TESTING.md)。 。 。 . ## 出版 SDK按照 [SDK 发布进程](https://gitlab.com/eyeo/browser-extensions-and-premium/extensions/extensions/-/wikis/SDK-release-process)。 。 。 . ## 活动 图书馆提供听众观察事件: - `EWE.allowlisting.onUnauthorized`: 拒绝允许列名请求时予以批准 - `EWE.filters`数字 : - `onAdded`: 添加新过滤器时发送 - `onChanged`: 当过滤器被启用或被禁用时,或当过滤器被禁用时,即被放出 元数据已更改 - `onRemoved`: 过滤器被取出 - `EWE.subscriptions`数字 : - `onAdded`: 添加新订阅时发出 - `onChanged`: 认购财产发生变化时被放行 - `onRemoved`: 订阅被删除时被接收 - `EWE.debugging.onLogEvent`: 调试输出时发出 - `EWE.reporting.onBlockableItem`: 当任何可阻塞项目匹配时被放出 使用 `addListener(...)` 订阅和订阅 `removeListener(...)` 以取消订阅. ## 示意图V3 见 [宣言V3文件](https://npmcn.com/package/%40eyeo/webext-ad-filtering-solution/docs/MANIFEST_V3.md) 为进一步 解释. ## 常见问题 ### @eyeo/webext-ad-filtering-solution 是什么？ iyo 的 Web 扩展辅助过滤解决方案 ### 如何安装 @eyeo/webext-ad-filtering-solution？ 在项目目录运行 npm install @eyeo/webext-ad-filtering-solution，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：mocha（10\.8\.2）、webextension-polyfill（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 subs-init、subs-fetch、subs-merge、subs-convert、subs-generate，可以用 npx subs-init 直接运行。 ### @eyeo/webext-ad-filtering-solution 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @eyeo/webext-ad-filtering-solution 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @eyeo/webext-ad-filtering-solution 可以商用吗？ @eyeo/webext-ad-filtering-solution 使用 GPL-3\.0 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以 GPL-3\.0 兼容许可开源，并附带专利与反锁定条款。仅内部使用不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。 ### @eyeo/webext-ad-filtering-solution 的下载量有多少？ 根据 npm 官方下载统计，@eyeo/webext-ad-filtering-solution 在 2026/10/14 – 2026/11/12 这 30 天内被下载 4,048 次，日均约 135 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @eyeo/webext-ad-filtering-solution 还在维护吗？ 最新版本 5\.0\.0 发布于 2026/11/13（今天）；至今共发布 47 个版本，其中过去 12 个月发布了 7 个；首次发布于 2023/09/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。