ROHITCRAFTSYT/shield-adblocker

# 🛡️ Shield AdBlocker 一款快速、注重隐私、基于 **Manifest V3** 的广告和跟踪器拦截器，适用于 Chromium 浏览器 （Chrome、Edge、Brave、Opera）。它在**网络层**拦截广告，并使用 **元素隐藏过滤**来隐藏残留的广告位——它的权限占用极小， 没有远程代码，也不收集任何数据。

## 功能 - **网络级拦截**涵盖 180+ 个知名广告/跟踪器网络 （Google Ads、DoubleClick、Taboola、Outbrain、Criteo、Amazon Ads、分析 信标等），通过 `declarativeNetRequest` 实现。 - **元素隐藏过滤** — 折叠广告容器和赞助商位，包含 通用规则以及针对 YouTube、Reddit、LinkedIn、X、Facebook 优化的选择器。 - **逐站点白名单** — 可在您希望支持的任何网站上暂停拦截。 - **全局开关**可通过弹窗切换。 - **真实的“本页已拦截”计数器**（使用 DNR feedback API）。 - **注重隐身** — 请参阅[隐身与检测](#stealth--detection)。 - **隐私设计** — 零遥测，自身不发起任何网络请求， 一切均在本地运行。请参阅 [PRIVACY.md](PRIVACY.md)。 ## 安装说明（加载未压缩的扩展） 1. 打开 `chrome://extensions`（或 `edge://extensions`、`brave://extensions`）。 2. 启用右上角的 **开发者模式** (Developer mode)。 3. 点击 **加载未压缩的扩展** (Load unpacked) 并选择此文件夹。 4. 固定 🛡️ 图标，即可开始使用。 包含详细图文步骤的完整指南请见 [docs/INSTALL.md](docs/INSTALL.md)。 ## 用法 点击工具栏图标： | 控制 | 作用 | | --- | --- | | **Blocking** | 整个扩展的总开关。 | | **Allow this site** | 将当前域名添加至白名单（在该处暂停拦截）。 | | **blocked on this page** | 在活动标签页中被拦截的请求数量。 | | **block rules active** | 当前已加载的网络规则数量。 | ## 工作原理 ``` ┌──────────────────────────┐ Web request ─────▶ │ declarativeNetRequest │ ──▶ blocked (ad/tracker) │ static ruleset (network) │ ──▶ allowed (everything else) └──────────────────────────┘ ▲ allowlist (per-site) ───────────┘ (high-priority session "allow" rules) Page DOM ─────▶ content script injects CSS to collapse ad slots ``` 详情请参阅 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 ## 隐身与检测 网络拦截运行在页面 JavaScript **底层**：对于页面而言，被拦截的广告请求看起来 就像普通的网络故障，且页面无法枚举 扩展的规则。元素隐藏层运行在内容脚本的 **隔离 世界** 中，**不会在页面上设置任何可识别扩展的全局变量或属性**，并且 使用 CSS **折叠**元素，而不是直接移除节点。 **诚恳的警告：**没有任何拦截器是真正无法检测的。坚决的反广告拦截 机制仍然可以推断出某个元素被隐藏或某个请求失败。此 扩展尽可能*最小化*其指纹特征；它不保证完全隐身。 ## 安全性 - 极小的权限、严格的 CSP、无 `eval`、不对动态数据使用 `innerHTML`、 无远程代码、自身不进行任何网络调用。 - Service worker 仅接受来自其**自身**扩展页面的消息，并 验证每一项输入。 完整的威胁模型请见 [docs/SECURITY.md](docs/SECURITY.md)。 ## 限制 - 内置列表（180+ 个网络）涵盖**常见**的广告/跟踪器域名，而未涵盖 EasyList 的全部内容。它易于扩展——只需将条目添加到 [`rules/ad-domains.txt`](rules/ad-domains.txt) 并将选择器添加到 [`src/content/selectors.js`](src/content/selectors.js)。 - “拦截每个网站上的所有广告”和“完全无法检测”属于尽力而为的目标，而非 保证——请参阅上述警告。 - 仅支持 Chromium (MV3)。此版本不针对 Firefox。 ## 更新拦截列表 拦截列表是生成的，而非手动编辑的。将域名添加到 [`rules/ad-domains.txt`](rules/ad-domains.txt)（每行一个）并重新生成： ``` npm run build:rules # rebuilds rules/network-rules.json from ad-domains.txt npm run lint # validates JSON + lints JS (also runs in CI) ``` `npm run lint:json` 会检查 `network-rules.json` 是否有效且与源列表**保持同步** — 如果您只编辑其中一个而不重新构建，CI 将会失败。 ## 项目布局 ``` manifest.json MV3 manifest rules/ad-domains.txt blocklist source (one domain per line) rules/network-rules.json generated declarativeNetRequest static blocklist scripts/build-rules.mjs compiles ad-domains.txt -> network-rules.json scripts/validate-rules.mjs CI guard: JSON valid + in sync src/background.js service worker (ruleset toggle, allowlist, messaging) src/content/selectors.js static cosmetic selectors src/content/cosmetic.js cosmetic filtering engine src/popup/ popup UI (html/css/js) icons/ extension icons docs/ install, architecture, security, screenshot .github/workflows/ CI (lint) ``` ## 贡献 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 [MIT](LICENSE)

标签：Chromium, DeclarativeNetRequest, Manifest V3, 广告拦截, 数据可视化, 暗色界面, 浏览器扩展, 网络安全, 网络安全, 自定义脚本, 调试辅助, 隐私保护, 隐私保护