用内容脚本拦截DOM注入节点：CSS选择器批量隐藏广告元素的工程实践

在现代浏览器扩展开发中，基于内容脚本的广告拦截是一种轻量且高效的方案。与传统的网络层拦截不同，内容脚本直接运行在页面上下文中，能够精确操控 DOM 节点，实现细粒度的元素隐藏或移除。they-live 项目展示了一种通过内容脚本拦截 DOM 注入、结合 CSS 选择器批量隐藏广告元素的工程化路径，其核心思路可供构建可移植浏览器广告拦截扩展时参考。

内容脚本与 DOM 拦截的基础架构

内容脚本是浏览器扩展体系中的一种特殊组件，它运行在目标网页的上下文中，能够访问和修改该页面的 DOM 结构。与后台脚本不同，内容脚本与页面共享同一文档对象模型，这使得它可以在页面渲染过程中或渲染完成后对特定元素进行拦截和操作。在广告拦截场景下，内容脚本的主要职责是识别广告容器节点并将其从可视范围内移除，或彻底从 DOM 树中删除。

构建一个基础的内容脚本拦截架构需要三个核心文件：manifest.json 用于声明扩展的权限和注入配置；content-script.js 承载核心的 DOM 操作逻辑；以及可选的 styles.css 用于声明需要全局隐藏的 CSS 规则。manifest.json 中的 content_scripts 字段定义了脚本注入的时机和目标页面范围，其中 matches 数组指定需要注入的域名模式，run_at 字段控制注入时机，document_start 能够在文档解析早期介入，而 document_idle 则在页面加载完成后执行。

{
  "manifest_version": 3,
  "name": "they-live-adblocker",
  "version": "1.0",
  "permissions": ["activeTab"],
  "content_scripts": [{
    "matches": ["<all_urls>"],
    "js": ["content-script.js"],
    "css": ["styles.css"],
    "run_at": "document_idle"
  }]
}

CSS 选择器批量隐藏的实现机制

CSS 选择器批量隐藏是内容脚本广告拦截中最直观的方案。其核心思想是维护一份广告元素的特征选择器列表，通过 querySelectorAll 批量匹配后统一应用隐藏样式。相比逐个元素单独处理，批量隐藏具有显著的性能优势，因为浏览器的 CSS 引擎在处理复杂选择器时已经过高度优化。

选择器的设计需要覆盖常见的广告容器特征。类名模式如 ad-container、advertisement、sponsored-content、promoted、native-ad 等是高频出现的标识。ID 属性同样具有规律性，许多网站的广告容器使用 ad-、advert-、banner- 等前缀作为 ID 命名规范。属性选择器如 [data-ad]、[data-advertisement] 能够匹配带有自定义数据属性的元素，这在现代前端框架构建的页面中尤为常见。结构选择器如 article > aside > div:nth-child (2) 则用于处理没有明确语义标记但位置固定的广告区域。

在实际工程中，建议采用分层策略组织选择器列表。第一层为通用选择器，覆盖主流广告网络的默认容器类名；第二层为站点特定选择器，针对各网站的个性化广告实现进行定制；第三层为动态生成的选择器，通过页面分析自动发现疑似广告元素。选择器列表应支持热更新机制，以便在不重新发布扩展的情况下实时更新拦截规则。

const SELECTORS = {
  common: [
    '[class*="ad-container"]',
    '[class*="advertisement"]',
    '[id*="ad-"]',
    '[id*="banner-"]',
    '[data-ad]',
    '[data-advertisement]'
  ],
  siteSpecific: {}
};

function hideElements(selectors) {
  selectors.forEach(selector => {
    try {
      document.querySelectorAll(selector).forEach(el => {
        el.style.setProperty('display', 'none', 'important');
      });
    } catch (e) {
      // Invalid selector, skip
    }
  });
}

MutationObserver 与动态内容拦截

静态页面的广告拦截相对简单，但现代 Web 应用大量使用动态内容加载技术，广告元素可能在页面初始渲染后异步注入，甚至通过 JavaScript 框架动态创建。传统的 DOM 查询方法无法捕捉这些后续插入的节点，需要引入 MutationObserver 作为持续监控机制。

MutationObserver 是浏览器提供的 DOM 变化观察接口，它能够监听目标节点及其子树的属性变更、字符数据变更以及子节点增删。对于广告拦截场景，最关键的是对子节点列表变动的监控。每次观察到的变化记录中，addedNodes 属性包含了新插入的节点，我们需要遍历这些节点，检测其中是否存在广告容器，并立即进行隐藏或移除操作。

配置 MutationObserver 时，subtree 选项确保对整个文档树进行监控，childList 选项开启对子节点变动的监听，attributes 选项则用于监控元素属性变化，因为某些广告 SDK 可能通过修改 class 或 data 属性来触发广告展示。观察器的回调函数应保持精简，避免执行耗时操作，否则可能影响页面的渲染性能。对于观察到的每个添加节点，建议进行快速的特征预检后再决定是否进行深度分析。

const observer = new MutationObserver((mutations) => {
  for (const mutation of mutations) {
    for (const node of mutation.addedNodes) {
      if (node.nodeType !== Node.ELEMENT_NODE) continue;
      if (isAdElement(node)) {
        node.style.setProperty('display', 'none', 'important');
      }
      // Check nested ad elements
      node.querySelectorAll?.(adSelectors.join(',')).forEach(el => {
        el.style.setProperty('display', 'none', 'important');
      });
    }
  }
});

observer.observe(document.body, {
  childList: true,
  subtree: true
});

性能优化与资源控制策略

内容脚本的性能开销直接影响用户体验和电池续航。批量 DOM 操作、频繁的选择器查询以及持续运行的 MutationObserver 都可能导致页面卡顿。工程实践中需要采用多重优化策略，在保证拦截效果的同时最小化性能损耗。

防抖与节流是控制回调频率的基本手段。 MutationObserver 的回调可能在一帧内触发多次，特别是在页面渲染复杂内容时。通过延迟执行拦截逻辑并合并多次触发，可以显著减少不必要的计算。使用 requestAnimationFrame 包装 DOM 操作能够确保在浏览器的合适时机执行修改，避免强制重排和重绘。

选择器查询应避免在每次回调中重新编译。正则表达式和选择器字符串应在模块初始化时预编译为可复用的数据结构。此外，利用 CSS 本身的继承特性，在根节点统一应用隐藏规则，比逐个元素设置样式更加高效。通过在文档头部注入一个 style 标签包含所有隐藏规则，可以利用浏览器的样式计算缓存。

function debounce(fn, delay) {
  let timer = null;
  return function(...args) {
    clearTimeout(timer);
    timer = setTimeout(() => fn.apply(this, args), delay);
  };
}

const observeAdditions = debounce((nodes) => {
  requestAnimationFrame(() => {
    for (const node of nodes) {
      hideMatchingAds(node);
    }
  });
}, 100);

可移植扩展的分发与维护

一个可移植的广告拦截扩展需要考虑多浏览器的兼容性和便捷的分发机制。Manifest V3 已成为 Chrome、Edge 等浏览器的新标准，但 Firefox 仍部分支持 Manifest V2。设计架构时应考虑抽象层，使得核心逻辑可以在不同 manifest 版本间共享。

权限最小化是安全设计的基本原则。广告拦截扩展通常需要访问所有网站的内容脚本权限，但可以通过声明式网域列表精确限定注入范围，而不是使用 <all_urls> 通配符。脚本本身应避免加载外部资源，防止注入恶意代码的风险。

维护方面，选择器规则库需要持续更新以应对网站的变化。建议设计一个远程配置机制，允许从服务器拉取最新的选择器列表。配置文件应支持版本号和增量更新，避免每次全量下载。同时，应建立用户反馈渠道，收集漏拦和误拦的报告，作为规则迭代的依据。

工程参数配置清单

构建一个生产级的内容脚本广告拦截扩展时，以下参数配置值得参考：MutationObserver 的防抖延迟建议设置在 50 至 200 毫秒之间，具体值可根据页面复杂度调整；CSS 隐藏优先使用 display:none 配合！important 覆盖内联样式；对于 iframe 内的广告，需在主文档和 iframe 文档中分别执行拦截逻辑；选择器列表建议按频率排序，高频匹配的选择器放在列表前端以减少遍历时间；初始 DOM 扫描应在文档 idle 状态执行，避免阻塞首屏渲染。

内容脚本广告拦截方案的核心优势在于轻量、透明且易于调试。与依赖网络请求拦截的方案相比，它能处理更多边缘场景，如本地渲染的广告和通过 JavaScript 动态插入的内容。通过合理的架构设计和性能优化策略，可以在保证拦截效果的同时维持页面的流畅运行。

资料来源：they-live 项目（https://github.com/davmlaw/they-live）及其相关浏览器扩展内容脚本架构文档。

web