高级参考 · 高级
网络过滤器语法
使用经过验证的网络规则子集,并了解例外、范围和被拒绝的行。
概述
Shield 接受许多拦截列表通用的过滤器语言中的一个有限子集。无法准确表示的行会被跳过。为了让某一行通过而删掉不熟悉的选项,可能会改变它的含义;请改为查看预览。
下面的示例使用保留的示例域名。它们说明的是规则的行为,而不是你应为真实服务安装的规则。请在你的规则中一次添加一行,检查其范围,并只应用你想要的更改。
语法
URL 模式
横向滚动以查看完整表格。
| 用途 | 语法和示例 | 预期效果和限制 |
|---|---|---|
| 匹配主机 | ||ads.example^ |
在主机名边界处匹配该主机及其子域名;不会匹配 notads.example。未指定类型的规则针对普通请求,而不是顶层页面导航。 |
| 锚定 URL | |https://cdn.example/ads.js| |
要求 URL 在这些位置开始和结束。协议、路径或查询发生变化都可能导致不再匹配。 |
| 匹配 URL 的一部分 | /ad/image/*$image |
匹配包含指定路径且后跟可变文本的图片请求 URL。末尾的通配符将它与用斜杠括起来的正则表达式区分开来。 |
| 使用通配符 | ||cdn.example/ads/* |
* 匹配可变文本;^ 匹配分隔符或 URL 结尾。包含多个通配符的模式有准入和处理量限制;不接受任意大小的模式。 |
模式使用 ASCII URL 文本。请不要包含 #fragment:浏览器不会在网络请求中发送 URL 片段。
类型、第一方/第三方和网站范围
横向滚动以查看完整表格。
| 用途 | 示例 | 预期效果和限制 |
|---|---|---|
| 限制请求类型 | ||ads.example^$script |
适用于脚本。其他类型包括 image、stylesheet、font、media、object、xmlhttprequest、subdocument、document、ping、websocket 和 other。别名包括 css、xhr、frame 和 doc。 |
| 排除某个类型 | ||ads.example^$~image |
排除图片。仅含否定的规则仍会排除顶层文档;它不会变成拦截页面的规则。 |
| 包含所有类型 | ||ads.example^$all |
明确包含顶层文档。$all,~script 包含其余已建模的类型。请谨慎使用。 |
| 限制第一方/第三方 | ||ads.example^$third-party |
当请求相对于发起它的网站属于第三方时适用。3p 是别名;first-party、1p、~third-party 和 ~3p 选择第一方。 |
| 限制发起请求的网站 | ||ads.example^$domain=news.example |
仅匹配由该主机发起的请求。可以按下方示例添加要排除的发起主机。网络 $domain= 范围中的实体通配符会被拒绝。 |
包含/排除范围在主机名之间使用 |,在要排除的主机前使用 ~:
||ads.example^$domain=news.example|~pay.news.example
例外和优先级
@@||ads.example^$script,domain=shop.example 允许由指定网站发起的匹配脚本请求。它不会暂停该网站上的全部保护。
匹配的普通例外优先于普通拦截。$important 拦截优先于普通例外;带有 $important 的例外又优先于该重要拦截。看起来更具体的文本并不构成通用的优先级规则。
对于整页例外,@@||shop.example^$document 会对匹配的顶层页面及其加载内容停用保护。这种形式不能添加第一方/第三方条件、发起域名范围、额外的资源类型或 $all。非例外的 $document 是对顶层文档的拦截,而不是暂停。
@@||news.example^$generichide 会停止该主机上的通用外观隐藏。网站专用的外观规则和请求拦截仍然有效。只接受纯主机锚点上的例外;路径、第一方/第三方条件和其他类型范围不会沿用到这种仅限主机的形式中。
弹出窗口目标
||popups.example^$popup 通过 Shield 的弹出窗口处理程序匹配弹出窗口的导航目标。@@||accounts.example^$popup,domain=shop.example 是限定范围的弹出窗口例外。它们不是脚本请求规则,也不会配置浏览器内置的弹出窗口拦截功能。
请不要将 $popup 与请求类型、$all、$generichide 或重定向操作组合使用:一行无法同时表示两种范围。如果是登录窗口出现问题,请先查看登录和付款窗口。
hosts 文件和条件块
使用黑洞地址 0.0.0.0、127.0.0.1、::1、:: 或 0 的标准 hosts 条目会被转换为主机锚点规则。例如,0.0.0.0 ads.example 等同于 ||ads.example^。其他用空白分隔的网络格式会被拒绝。
列表可以使用嵌套的 !#if、!#else 和 !#endif,并配合 !、&&、|| 和括号。条件会根据 Shield 的软件包目标进行评估。可识别为真的共享条件包括 true、env_mv3 和 cap_user_stylesheet;env_chromium 和 env_firefox 取决于目标。未知常量评估为假。这些指令用于选择列表分支,而不是判断实时页面的状况。
无害重定向
只接受一组固定的资源:redirect=noopjs 或 redirect=noop.js 提供空脚本;redirect=nooptext 或 redirect=noop.txt 提供空文本;redirect=noopjson 提供 {}。例如,当规则生效时,||ads.example/tracker.js$script,redirect=noopjs 会用无害脚本替换原脚本。
这些是软件包内置的替换资源,不是指向任意 URL 的重定向,也不是对第三方库的完整模拟。未知资源名称和例外规则上的重定向操作会被拒绝。优先级相同的竞争性硬拦截可能会胜过重定向。
限制
正则表达式网络过滤器、removeparam、csp、badfilter、redirect-rule 和未知修饰符会被整行拒绝。本参考不承诺与 EasyList、uBlock Origin 或 AdGuard 的所有功能兼容。此处未列出的语法,并不表示它已经过测试并被拒绝。
已接受的规则仍可能超出浏览器容量,或被保护设置和例外覆盖。请查看预览和保护状态;配置了规则并不代表它在页面上产生了效果。
示例
一组范围精确的拦截和例外:
||ads.example^$script,third-party
@@||ads.example^$script,domain=checkout.example
第一行拦截匹配的第三方脚本。第二行允许由 checkout.example 发起的匹配脚本请求。重新加载后,请测试网站的实际操作流程;被允许的请求也可能放行广告或跟踪。