Nvirya AdGuard 官方知识库

当前版本： v11.7.0 | 开源协议： MIT | 执行模型： 用户脚本 (@run-at document-start)

Nvirya AdGuard（控制面板标题显示为 Nvirya AdGuard X）是一款开源用户脚本（Userscript），旨在兼容的移动端与桌面端浏览器中过滤已知广告元素、拦截恶意弹窗与跨站自动跳转、解除隐形点击陷阱遮罩，并提供直观的页面元素清理工具。

本知识库详细说明脚本的工作原理、在浏览器安全边界内能做到与不能做到的事项、常见网页兼容性问题的排查方法，以及如何提交清晰的错误反馈。

适用人群#

Nvirya AdGuard 面向以下用户设计：

移动端浏览器用户：包括 iOS/iPadOS（如搭配 Stay 扩展的 Safari 浏览器）以及支持用户脚本扩展或内置脚本管理器的 Android 浏览器（如 XBrowser，或安装 Tampermonkey / Violentmonkey 的 Firefox / Chromium 浏览器）。
桌面端浏览器用户：希望通过标准用户脚本管理器获得页面级广告过滤、外部跳转确认以及交互式元素选择器。
经常访问广告密集型媒体、资讯或文件下载网站的用户：在这些网站上，透明点击遮罩、背后弹窗（pop-under）、页面滚动锁定或未授权的第三方跳转经常干扰正常浏览。

与独立应用程序或系统级网络过滤器不同，用户脚本是由用户脚本管理器注入到网页中的 JavaScript 脚本。

当您打开匹配 *://*/* 的网页时，用户脚本管理器会在 document-start 阶段（大多数页面脚本和 DOM 元素加载完成之前）注入 Nvirya AdGuard。在页面环境中，脚本会执行以下操作：

注入修饰性 CSS 规则（<style data-nvirya-cosmetic>）与站点自定义规则（<style data-nvirya-site-rules>），隐藏已知的广告容器与赞助内容槽位。
使用浏览器的 MutationObserver API 监听动态 DOM 变化，折叠新插入的广告占位符、清除残留的黑色背景遮罩并解除透明点击陷阱。
在执行环境允许注入主世界（main-world）脚本时，包装页面级 JavaScript API——包括 Window.fetch、XMLHttpRequest、Navigator.sendBeacon 与 window.open。
在独立的开放式 Shadow DOM 容器（<div data-nvirya-ui>）中渲染控制面板，方便您在当前页面随时暂停防护、解除滚动锁定、手动隐藏元素或查看第三方域名连接。

由于 Nvirya AdGuard 完全作为浏览器标签页内的用户脚本运行，其实际表现取决于您的浏览器内核、用户脚本管理器、注入时机、授予的权限以及目标网站的具体架构。

您可以合理预期的功能	Nvirya AdGuard 无法保证的事项
隐藏标准横幅广告位、Google AdSense 容器（`ins.adsbygoogle`）以及受支持搜索与社交页面上的赞助帖子	在所有网站或视频平台上实现 100% 的广告拦截
拦截由 JavaScript 发起的 `window.open` 广告弹窗与不受信任的跨站自动跳转	替代拥有特权 API 的浏览器扩展（如 uBlock Origin）或系统级 VPN/DNS 拦截器
在打开不受信任的外部链接或可疑第三方下载跳转前弹出确认提示	拦截绕过页面 JavaScript 或在脚本注入前发生的浏览器原生网络请求
在开启视频保护时，自动跳过或快进 YouTube 及标准 HTML5 播放器中检测到的视频广告	对服务端拼接或与媒体流深度耦合的视频广告实现零延迟瞬间移除
在支持主世界脚本注入的桌面端与 Android 浏览器上绕过常见反广告拦截弹窗	绕过所有反广告拦截系统、付费墙（Paywall）或服务端校验（尤其是在 iOS WebKit 沙盒隔离环境下）
通过作用域豁免机制保留 Cloudflare、Turnstile、hCaptcha、reCAPTCHA 与 DDoS-Guard 验证组件	自动解答或绕过 CAPTCHA 验证码、机器人检测或 DDoS 安全验证挑战

运行 Nvirya AdGuard v11.7.0 需要满足以下条件：

兼容的用户脚本管理器，需支持脚本元数据头（@run-at document-start、@all-frames true）及以下 @grant 权限：
- GM_addStyle
- GM_getValue 与 GM_setValue（若不可用则按站点回退至 window.localStorage）
- GM_registerMenuCommand（可选，用于浏览器工具栏快捷菜单）
- GM_xmlhttpRequest（用于检查更新、远程域名列表同步和提交问题反馈；在 CORS 允许时可回退至 fetch）
- unsafeWindow（用于在受支持环境中桥接主世界防护）
经源码验证的分发地址（来自脚本元数据头）：
- 标准安装与更新 URL： https://raw.nvirya.com/adguard/nvirya-adguard.user.js
- iOS / iPadOS Stay 一键安装 URL： stay://x-callback-url/install?scriptURL=https%3A%2F%2Fraw.nvirya.com%2Fadguard%2Fnvirya-adguard.user.js

注意： 请始终从上述官方分发地址安装或更新脚本。由于不同操作系统和应用商店中的用户脚本管理器导入方式不同，请参考您所用管理器的说明导入 .user.js 链接。

请通过以下指南深入了解各项专题：

工作原理 — 了解用户脚本、浏览器扩展与 VPN/DNS 过滤器的架构差异，以及 v11.7.0 的三阶段启动流程、DOM 过滤与 JavaScript 网络钩子机制。
功能指南 — 掌握概览、设置与关于标签页中每个控件的用法，包括快捷悬浮按钮、隐藏页面元素选择器、连接日志与外部链接确认弹窗。
已知限制 — 详细了解 YouTube 移动端广告处理延迟原因、VPN/DNS 过滤工具（Shadowrocket、Surge、Loon）交互影响、Android CPU/电池开销控制以及 iOS Safari/WebKit 沙盒限制。
故障排除指南 — 针对残留暗色遮罩、Cloudflare/CAPTCHA 验证循环、下载链接无法打开、Google/Bing 翻译异常、页面卡顿与漏拦广告的分步恢复指南。
远程规则与高级配置 — 配置从远程 URL 同步域名拦截列表，以及导出或导入站点自定义 CSS 规则。
问题反馈与报告 — 查看提交反馈时收集的完整字段、URL 脱敏逻辑、30 秒速率限制及隐私边界。
常见问题解答 (FAQ) — 针对拦截范围、平台差异、更新后页面异常及单站点暂停等 11 个常见问题的简明解答。