WebToApp 的 Hosts 拦截机制:带 Cosmetic 过滤的去广告器,从预览到导出 APK 全链路解析

原创2026-09-16 15:06:452,499 阅读

WebToApp 的 Hosts 拦截机制:带 Cosmetic 过滤的去广告器,从预览到导出 APK 全链路解析

WebToApp 内置了一个基于 hosts 规则、并叠加 cosmetic(外观)过滤的去广告器:它既能拦截广告域名的网络请求,又能通过 CSS 隐藏页面上的广告元素,并且去广告能力同时贯通"应用内预览"和"导出的 APK"两端。本文以仓库中 Hosts 拦截指南 为核心,结合 AdBlocker 引擎实现、缓存层 与 APK 构建器 的源码,讲清这套机制的功能边界、规则语法、匹配链路和导出方式,读完你可以既会用它管理订阅,也能理解其底层匹配原理。

功能概览:Hosts 拦截页面提供了什么

去广告入口位于主界面 ⋮ → Hosts 拦截(对应 主界面"更多"菜单)。整个页面由 HostsAdBlockScreen 实现,对应文档列出的五项核心能力:

能力 说明 源码依据
生效规则数 查看已加载的拦截规则数量,顶部 SummaryCard 展示导入规则数、生效 hosts 数、来源数 HostsAdBlockScreen.kt#L236-L243 调用 getImportedHostsRuleCount() / getHostsFileRuleCount()
来源管理 下载预设订阅、从文件或 URL 导入、删除来源;自定义导入记录显示名称,以独立卡片提供启用/禁用/删除 importHostsFromFile() / importHostsFromUrl() / removeHostsSource() / setHostsSourceEnabled()
内置列表 20 个社区过滤列表(EasyList、uBlock Origin、AdGuard、AdAway,外加 8 个语言专属列表) AdBlocker.getPopularHostsSources()
搜索 按名称、描述、URL 查找特定规则来源 HostsAdBlockScreen.kt#L162-L190 的 matchesQuery()
清除 移除全部已加载规则,操作前带确认弹窗 showClearDialog 状态 + clearHostsFileRules()

页面顶部除了汇总卡片外,还提供"从文件导入"与"从 URL 导入"两个动作入口,以及"全部 / 已下载 / 未下载"三种筛选 Chip(见 HostsAdBlockScreen.kt#L86-L90 的 HostsFilter 枚举)。

内置的 20 个社区列表

getPopularHostsSources() 返回的预设来源共 20 个,与文档描述一致:

  • EasyList 系:EasyList(主国际列表)、EasyPrivacy(追踪/分析拦截)、EasyList Germany / France / Dutch / Italy / Spanish / Portuguese / China —— 覆盖德法荷意西葡中等 8 个语言区;
  • uBlock Origin 系:uBlock Filters(默认过滤)、uBlock Privacy(隐私过滤);
  • AdGuard 系:AdGuard Base、AdGuard Tracking Protection、AdGuard Annoyances(Cookie 横幅等打扰类)、AdGuard Japanese、AdGuard DNS Filter;
  • hosts 文件系:StevenBlack Hosts、AdAway Default、Peter Lowe's List、1Hosts Lite。

这些预设来源的 URL 硬编码在 AdBlocker.kt#L219-L324,部分描述文案通过 i18n 模块 的 Strings 取多语言字符串。

规则从哪里来:预设、文件与 URL 三种导入路径

从 URL 导入订阅

importHostsFromUrl() 的完整链路(AdBlocker.kt#L2200-L2302):

  1. 先查 24 小时 URL 缓存:通过 AdBlockFilterCache.getCachedUrlContent() 命中则直接复用,不重复下载;
  2. 下载:HttpURLConnection,连接超时 15s、读取超时 30s,User-Agent 为 WebToApp/1.0;按 8KB 分块读取,进度回调以 150ms 节流上报(源码注释提到 AdGuard Base 约 6.4MB、会产生约 800 次回调,因此必须限流),UI 侧即 HostsAdBlockScreen.kt#L192-L223 中展示的 DownloadProgress 进度条;
  3. 落盘:内容写入 source_content 目录(以 URL 的 MD5 命名),URL 缓存另存于 url_cache;
  4. 元数据:记录显示名称(优先 ABP 列表头 ! Title: ...,否则由 URL 推导)、上次刷新时间戳,并从列表头解析 ! Expires: N days/hours 作为刷新周期;
  5. 解析入库:parseFilterContent() 解析全部规则并登记来源规则数。

从文件导入

importHostsFromFile() 走系统文件选择器(ActivityResultContracts.GetContent),读取文本后按同样逻辑解析;来源键形如 file:<uri>,显示名称优先取系统的 DISPLAY_NAME,取不到则从 URI 末尾文件名推导。

自定义来源的独立卡片

用户导入的来源(非预设 URL)由 getCustomHostsSources() 单独列出,每个来源带导入时记录的显示名称,在界面上渲染为独立卡片,可单独启用/禁用/删除。启用/禁用只改变注册表标志并触发 rebuildHostsFromSourceContents() 从磁盘内容重建规则,不重新下载。

持久化结构

去广告器维护两份核心持久化文件(位于应用私有 filesDir):

  • adblock_hosts.txt —— 纯 hosts 形态的域名列表;
  • adblock_hosts_sources.txt —— 来源注册表(tab 分隔):url \t 规则数 \t 启用标志 \t 显示名 \t 上次刷新时间 \t 刷新周期,即注册表 v3 格式,解析逻辑见 hydrateSourceRuleCountsFromDisk()。

另有二进制编译状态 adblock_cache/compiled_state.bin(缓存版本 5),把 hosts 集、网络规则、cosmetic 规则、scriptlet 规则整体序列化,冷启动时由 loadCompiledState() 直接恢复内存引擎,免去重新解析大列表;若加载时抛 OutOfMemoryError,会主动删除缓存文件以避免"每次冷启动都 OOM"的死循环(见 AdBlockFilterCache.kt#L243-L257)。

规则格式:同时兼容 hosts 文件与 ABP/uBO/AdGuard 过滤语法

parseFilterContent() 先用前 20 行嗅探格式:出现 [Adblock...]、!、||、@@、##、#@# 之一即判定为 ABP 格式,逐行走 parseAndAddRule();否则按 hosts 文件逐行解析。

hosts 文件解析

parseHostLine() 支持三种行形态:||domain^ 的 ABP 风格、0.0.0.0 domain / 127.0.0.1 domain 的标准 hosts 行(含 # 注释剥离)、以及裸域名。isValidHost() 会过滤非法项:空/超长(>253 字符)、首尾点、双点、纯 IP、localhost 等。解析出的域名统一小写存入 hostsFileHosts。

ABP 风格网络规则

parseNetworkFilter() 处理形如 ||ads.example.com^$third-party 的规则,支持的修饰符($ 之后,逗号分隔)包括:

  • 类型限定:script、stylesheet/css、image、font、xmlhttprequest/xhr、media、websocket、object、subdocument、document、ping、other(映射表见 AdBlocker.kt#L679-L695);~ 前缀表示排除该类型;
  • 方向限定:third-party/3p、~third-party/first-party/1p;
  • match-case(默认不区分大小写)、important(接受但当前无特殊处理);
  • domain=a.com|~b.com 页面域名限定/排除;
  • @@ 前缀为例外规则。

两个工程细节值得注意:

  • 锚点索引:|| 开头的规则提取锚点域名,按域名建倒排索引(anchorDomainIndex),匹配时从请求域名逐级向上查索引,避免全表扫描;无锚点规则另有 unanchoredFilterIndex 单独管理;
  • 惰性正则编译:ABP 模式到正则源串的翻译(translateAbpPattern,处理 ||、|、*、^、/regex/ 等语义)在导入时完成,但昂贵的 Regex 编译推迟到首次命中——源码注释解释了原因:一份 10 万条规则的大列表若导入时全量编译,约 100MB+ 的 Pattern 对象会在 256MB 堆设备上 OOM,而导出时还要构建第二套引擎。

Cosmetic 规则与 scriptlet

parseAndAddRule() 按分隔符优先级 #@$#、#$#、#@?#、#?#、#@#、## 分流:

  • 隐藏类 ##selector:普通 CSS 选择器、uBO 的 :style(...) 伪类(仅重设样式不隐藏);uBO 过程化伪类中实现了 :has-text()、:upward()、:remove()(编码为 t:text / u:arg / r 操作链,交给页面端脚本求值),其余 20 余种过程化伪类在解析期直接丢弃——注释指出无效选择器会污染整条逗号拼接的隐藏批次(对应 issue #823);
  • 注入类 domain#$#完整CSS / #@$# 例外:AdGuard 的完整 CSS 注入规则;
  • scriptlet 类 ##+js(...) / #%#//scriptlet(...):内置了 abort-on-property-read、abort-current-inline-script、set-constant、remove-attr、remove-class、prevent-fetch、prevent-xhr、nano-setTimeout-booster 等十余种脚本片段生成器(AdBlocker.kt#L1972-L2170),生成的 JS 会在页面侧统一注入。

请求匹配链路:一个 URL 是如何被判定拦截的

核心入口是 shouldBlock(url, pageHost, resourceType, isThirdParty),判定顺序(见 AdBlocker.kt#L872-L953)为:

  1. 白名单直通:请求域名命中内置 SAFELIST_HOSTS(约 200 项 CDN、登录、支付、地图、播放器、推送类域名,如 cdn.jsdelivr.net、fonts.gstatic.com、js.stripe.com、accounts.google.com)直接放行,防止误伤第三方 SDK;
  2. 资源类型保护:document(主文档)不拦;font 不拦;非第三方样式表不拦;
  3. 关键资源保护:URL 命中 ESSENTIAL_RESOURCE_REGEX(jquery/react/api/checkout/sw.js/manifest.json 等路径特征)放行,降低把页面功能拦碎的概率;
  4. 结果缓存:以 url + pageHost + 类型 + 是否第三方 组合为键查 LRU 缓存(容量 2048)。注释特别说明:例外规则 @@||ads.com$domain=example.com 的结果与页面域名相关,所以缓存键必须含 pageHost,调用方不能在每次页面加载时清缓存;
  5. 正式判定(shouldBlockInternal):
    • 请求域名逐级(含上级域)命中 exactHosts 或 hostsFileHosts → 例外规则未命中则拦截;
    • 例外规则优先:任何例外命中直接放行;
    • 网络拦截规则命中则拦截;
    • 第一方兜底:非第三方请求命中 FIRST_PARTY_AD_PATH_REGEX(/ads/、/banner/、/doubleclick/ 等 20 余种广告路径)且类型为 script/xhr/subdocument 时拦截。

被拦截的资源不会返回空 404,而是由 createEmptyResponse(resourceType) 返回"无害替身":脚本返回 /* blocked */、样式返回 /* blocked */、图片返回 1x1 透明 GIF、XHR 返回 {}——这种"返回合法空内容"的策略能减少页面脚本报错。

WebView 侧调用 shouldBlock(WebResourceRequest) 时会先由 inferResourceTypeFromRequest() 从 Accept 头推断资源类型,Accept 头不可用再退回文件扩展名兜底。

Cosmetic 过滤:MutationObserver 隐藏广告元素

文档提到"基于 MutationObserver 的 cosmetic 过滤器会隐藏被 cosmetic 规则匹配的元素",其实现要点:

  • 每页一份编译产物:getCosmeticFilterCss(pageHost) 按页面域名过滤出适用的隐藏选择器、样式覆盖(:style(...))与 AdGuard 注入 CSS,并与内置选择器(ins.adsbygoogle、<a href="https://link.gitcode.com/i/a83a8a5ba0940d7498a5903699cced9f" target="_blank">id^="google_ads_"]、[data-ad-slot]、[class*="taboola"] 等,见 [AdBlocker.kt#L1068-L1103)合并;
  • 分批隐藏:隐藏选择器按每 50 个一批打包成"逗号拼接批次"(hideBatches),DOM observer 按批查询——单批里一条选择器无效不会导致同批其余规则跳过隐藏(同样是 #823 的防御);
  • 版本化缓存:cosmetic 产物按 pageHost 记忆化,版本号 cosmeticVersion 只在规则集变化(初始化、来源启用/禁用、订阅编辑)时递增并清空缓存,避免每次导航都全量扫描 cosmetic 规则;
  • 过程化规则::has-text() / :upward() / :remove() 规则不参与 CSS 生成,而是输出 [{"b":baseSelector,"o":["t:text","u:2","r"],"a":0}] 形式的 JS 字面量交给页面端 observer 脚本求值;
  • 反检测配套:getAntiAdblockScript() 会生成一段"反反广告"脚本——投放假广告诱饵元素、伪造 google_ad_status 等检测变量、移除广告拦截警告墙、对诱饵元素劫持 getComputedStyle、拦截检测信标请求(见 AdBlocker.kt#L2627-L2798)。

默认规则集

initialize(customRules, useDefaultRules = true) 可启用内置默认集:约 200 个常见广告/统计域名(DEFAULT_AD_HOSTS,含 Google 系、AdX、baidu 系、穿山甲/pangle 等移动广告平台)、一批 ABP 网络规则(DEFAULT_NETWORK_RULES,含 @@||sentry.io^、@@||js.stripe.com^ 等自带例外)、以及约 90 条通用 cosmetic 规则(DEFAULT_COSMETIC_RULES,覆盖 ad-* 类名、cookie 横幅、弹窗、像素探针等)。

订阅自动刷新:Expires 周期与失败退避

订阅不是"下载一次就完事"。prepareRuntimeFilters() 在每次运行时被调用(见 WebViewActivity.kt#L1504),它会记录本次选中的订阅集合并触发后台 kickSourceRefresh:

  • 周期来源:列表头 ! Expires: N days/hours,经 expiresIntervalMs() 钳制在 6 小时 ~ 14 天之间(默认 24 小时),防止恶意或手误的表头造成热循环;
  • 失败退避:某来源下载失败后,1 小时内不再重试,且保留旧内容继续生效(fail-soft);
  • 重建一致性:刷新完成后按"上次 prepareRuntimeFilters 的参数"(lastPrepSelected + lastPrepCustomRules)精确重建同一个规则宇宙,重建过程持有引擎互斥锁,不会与前台调用竞争。

这些行为有单测覆盖,例如 AdBlockerHostRuntimeTest.kt 验证了"initialize 清空后能重新应用缓存订阅""compileRulesText 包含所选订阅与自定义规则"等场景,AdBlockLazyRegexTest.kt 则针对惰性正则编译做了验证。

去广告贯通预览与导出:两份文档的关键说明

关联文档"说明"部分的两条要点,在源码中都能找到对应实现。

预览端

宿主 App 的去广告服务(即上文 AdBlocker 引擎)直接服务 WebView 预览:进入应用预览时 prepareRuntimeFilters() 按当前应用的配置准备规则集,WebView 的 shouldOverrideUrlLoading/资源拦截路径调用 shouldBlock() 判定并返回空响应。

导出端:编译后的规则集随 APK 发布

导出时 ApkBuilder.kt#L1576-L1594 的逻辑:当应用配置 config.adBlock.enabled 为真时,用独立的新 AdBlocker 实例调用 compileRulesText(context, subscriptionUrls = config.adBlock.subscriptions) 重新编译该应用选定的订阅,把结果以压缩条目写入 APK 的 assets/wta_adblock_compiled.txt,日志记录 "AdBlock compiled rules bundled (N bytes)"。这正是文档所说"宿主去广告器服务预览,编译后的规则集随生成的 APK 一起发布"。getCompiledRulesText() 的输出格式为:hosts 域名统一转成 ||domain^ 网络规则行,再加上原始网络/cosmetic 规则文本——导出的 APK 运行时用它重新构建本地引擎,不需要联网拉取订阅。

注意一个实现事实:导出走的是 compileRulesText(按订阅 URL 重建),而预览走的是 prepareRuntimeFilters(运行时引擎),两条路径共享同一套解析与编译代码,但引擎实例相互独立,这也解释了源码中"导出构建第二套引擎"的内存考量。

每应用配置:隐私卡片下的订阅选择器

去广告按应用配置:在 隐私与加固 主题下的 广告拦截卡片 中,每个应用可独立开关去广告并选择订阅来源——选择器同时提供内置列表和你在 Hosts 拦截页导入的自定义来源(源码中对应 config.adBlock.subscriptions 列表与 config.adBlock.rules 自定义规则)。Hosts 拦截页相当于"全局素材库":下载、管理所有订阅;隐私配置卡片相当于"按应用装配":为每个应用勾选生效的列表。

小结:这套去广告器的设计取向

从源码结构看,WebToApp 的 Hosts 拦截不是简单的域名黑名单,而是一套面向低端设备内存约束做了大量取舍的轻量过滤引擎:

  • 格式兼容宽:同时吃 hosts 文件、ABP、uBO(含部分过程化伪类与 :style)、AdGuard #$# 注入和 scriptlet 规则,内置 20 个社区列表可直接订阅;
  • 内存防御深:正则惰性编译、二进制编译状态缓存(带 OOM 自毁)、LRU 匹配结果缓存、进度回调节流、OOM 时保留部分规则集继续运行;
  • 误伤控制:内置约 200 个白名单域名、关键资源路径保护、白名单类型(document/font)直通;
  • 闭环能力:订阅自动刷新(Expires 周期 + 失败退避)、每应用订阅选择、编译规则随 APK 发布,使去广告效果在预览和导出产物中一致。

如果你只想动手配置,路径也很短:主界面 ⋮ → Hosts 拦截 下载或导入 1~2 个列表(如 EasyList + 对应语言列表),再到目标应用的"编辑通用配置 → 隐私 → 广告拦截"中开启并勾选这些来源,预览即可生效;导出 APK 后该规则集会随包内置,离线环境同样工作。

登录后查看全文