静态过滤规则语法 - fang5566/uBlock GitHub Wiki

uBlock Origin（uBO）支持绝大多数 EasyList 的过滤规则语法，你可以参考 Adblock Plus（ABP）和 AdGuard （AG）现有的过滤规则语法文档。

uBO 不支持一些很特殊的应用场景，但进一步扩充了 EasyList 的过滤规则语法，这些扩充语法或许还为 AdGuard 自身的扩充语法所共享。更另类的场景可到这里查阅。

从 1.26.0（合并了 1，2）版本开始, 超长规则会被分隔为多行：首行末尾添加空格和反斜杠符号，次行前留四个空格。注意语法高亮功能目前尚不可用。

从 1.46.1b15 版本开始，你可以将基于正则表达式的值用作扩充的静态过滤规则的目标域。例如：/img[a-z]{3,5}\.buzz/##+js(nowoif)。从维护角度出发没有其他实际解决方案时，才可谨慎使用此方法。请记住 UBO 得遍历所有基于正则表达式的值，而不像普通域名或基于实体的值只需要查找即可。

• 不支持的语法
• 预解析的语法
• 扩充的语法
  • 静态网络过滤
  • 静态扩充过滤
    • 实体
    • 修饰规则
      • 过程式修饰规则 ↪
• 动作操作符 - HTML 规则 - 小脚本插入 - 资源库 ↪

不支持该语法。在白名单规则里使用 document 选项是用来禁用 uBO，而在静态例外规则里使用 document 选项则是为了支持“可接受广告”特性，但 uBO 不支持该特性。

该选项不再支持的原因是 uBO 本身应该由用户自己根据意愿来禁用（通过受信任的站点），而不是让外部规则列表来替他们做决定。

注意：在某些场景下仍会生效，即明确使用过滤规则的 document 选项来取消严格屏蔽功能。

不支持该语法。

该选项是和例外规则一起使用，用来禁用特定页面上的 通用 网络规则。这里说的 通用 是指网络规则不包含 domain= 选项。而像是 ||example.com^ 这样的规则仍视作通用规则。

该选项不受支持的原因是在应用的网站会导致大量过滤规则被悄悄禁用。

举个例子，在特定站点使用时，genericblock 选项会导致 hosts 文件里面所有的规则被禁用，包括来自恶意网站规则列表里的规则。EasyPrivacy 和其他反跟踪列表也包含无数的“通用”规则，该选项也会导致这些规则被禁用。

该选项会在内部翻译为 generichide。elemhide 是和例外规则一起使用，用来禁用页面上所有的修饰规则。现在“禁止修饰规则生效”的开关就可以做到了。

现已支持 从 uBO 1.23.0 开始重新支持该选项，该选项也可写作 ehide。

在 1.23.0 之前的版本它会在内部翻译为 generichide。elemhide 选项只能在“禁止修饰规则生效” 开关内使用。

请记住 generichide 是一个与修饰规则有关的选项，使用时不会对隐私产生什么负面的影响，毕竟修饰规则在保护隐私方面没什么价值。

uBO 1.16.0 即更高版本支持预解析的语法。预解析的语法以 !# 打头，表示旧版本的 uBO 或其他过滤工具会将预解析的语法视作注释并丢弃。

预解析的语法在规则列表内容解析之前执行，进而影响规则列表的最终内容。

!#include 语法允许在语法出现处导入另一份规则列表，使得规则列表维护人员既可以创建 uBO 专用的规则，又能保证列表兼容其他过滤工具。其他过滤工具会忽略 !#include 语法，将其视作注释并丢弃。而 uBO 会尝试加载 [文件名]（子列表）处出现的资源并将内容载入当前列表。

这里的子列表必须和主列表位于同一目录下，不允许加载当前列表路径之外的子列表。

正确的用法：

• !#include ublock-filters.txt
• !#include ublock/filters.txt

错误的用法：

• !#include https://github.com/uBlockOrigin/uAssets/blob/master/filters/filters.txt
• !#include ../filters.txt

!#if 语法允许维护人员创建仅在满足（或不满足）特定条件时才会解析的规则列表区域，例如用该语法创建只在特定浏览器生效的规则。

下面这个例子是只在 uBO 作为一个 Firefox 附加组件运行时才编译这部分规则：

!#if env_firefox
...
!#endif

在另一个例子中，只在 uBO 不 作为一个 Firefox 附加组件运行时才编译这部分规则（你可以用 ! 表示相反）：

!#if !env_firefox
...
!#endif

我们是在与 AG 开发人员讨论后决定支持这些预处理器（pre-processor）语法。具体参见 https://github.com/AdguardTeam/AdguardBrowserExtension/issues/917。

1.50.1b9 版本开始，uBO 完全兼容 AdGuard 过滤规则列表中的 !#if 语法。

uBO 仅支持下列令牌，其他内容会被忽略：

从 1.22.0 版本开始，你可以使用 !#if false 语法禁用一大块规则，而不用移除它们。

!#if false
...
!#endif

此前版本你可以使用 !ext_ublock，因为在 uBO 中该令牌始终为 true。

从 1.50.1b9 版本开始，你可以使用 !#else 语法：

!#if cap_html_filtering
example.com##^script:has-text(fakeAd)
!#else
example.com##+js(rmnt, script, fakeAd)
!#endif

下面是 uBO 针对 ABP 增加的语法。

• _ (或称 “noop”)
• * (或称“所有的 URL”)
• $1p ($first-party)
• $3p ($third-party)
• $all (所有基于网络的类型 + $popup + $document + $inline-font + $inline-script)
• $badfilter
• $css ($stylesheet)
• $cname
• $denyallow
• $document
• $domain ($from)
• $elemhide ($ehide)
• $font
• $frame ($subdocument)
• $genericblock Not supported
• $generichide ($ghide)
• $header
• $image
• $important
• $inline-script
• $inline-font
• $match-case
• $media
• $method
• $object
• $other
• $permissions
• $ping
• $popunder
• $popup
• $script
• $specifichide ($shide)
• $strict1p
• $strict3p
• $to
• $webrtc example.com##+js(nowebrtc)
• $websocket
• $xhr ($xmlhttprequest)
• $csp
• $empty ($redirect=empty)
• $mp4 ($redirect=noopmp4-1s)
• $redirect
• $redirect-rule
• $removeparam
• $replace（仅来自值得信任的来源）
• $uritransform（仅来自值得信任的来源）

uBO 也支持解析类似于 HOSTS 文件这样的资源，所有 HOSTS 文件条件在 uBO 看来在语法上都等同于使用 ||hostname^ 形式的规则。

但因此与基于模板的 ABP 过滤规则语法引出了一些歧义。例如下面这条过滤规则：

example.com

ABP 过滤规则语法会解释为“对在任何位置出现 example.com 的 URL 所产生的网络请求均予以屏蔽”。

但 uBO 会解释为“屏蔽 example.com 网站及其所有子域名产生的网络请求”，等同于 ||example.com^这条规则。请注意这样包括屏蔽网站本身的主文档，参见“严格屏蔽”和 document 规则选项。

因此在 uBO 里，任何视作有效主机名的规则都会被当作等同于 ||example.com^ 形式的规则。如果你想让它按照 ABP 的解释在语法上被解析，只要在末尾加上一个通配符：

example.com*

如果规则是一个文件名，最好是在开头处加上一个斜杠符号确保它不会被解析成主机名：

/example.js

相关文章：

• uBO 里的 hosts 文件：屏蔽得越多，方式也越多
• 系统层面的 Hosts 文件 vs uBO 里的 hosts 文件

也可参见：

• 缩小网络规则生效范围的选项

这只是一个占位符。

它是为了解决带有正则表达式参数（因为被两个斜杠包裹）的 $removeparam 过滤规则被检测为普通的正则表达式规则的问题：

/ad-$removeparam=/^foo=bar\d$/,_

从 1.50.1b11 版本开始，你也可以使用 _ 选项解决该可读性问题，它支持在一条规则里面有多个 _ 选项实例：

||example.com$_,removeparam=/^ss\\$/,_,image
||example.com$replace=/bad/good/,___,~third-party

使用通配符 * 可以将过滤规则应用到所有的 URL。不过不建议你这么做，除非你接下来使用过滤规则选项缩小规则生效范围，例如下面这样：

• *$third-party：屏蔽所有第三方的网络请求。
• *$script,domain=example.com：屏蔽所有在 example.com 获取脚本资源的网络请求。

相比这样宽泛的静态规则，通常使用动态过滤规则代替要方便得多。

等同于 uBO 里的 first-party 选项，即与 third-party 选项 (~third-party) 相反。

其过滤规则会匹配发往当前域名的请求。

等同于 third-party 选项。

其过滤规则会匹配发往非当前域名的请求。

从 uBO 1.20.0 版本开始引入。

这个 all 选项等同于指定了所有基于网络的资源类型 + popup、document、inline-font、inline-script。

示例：

||bet365.com^$all

上述规则会屏蔽所有来自 bet365.com 的网络请求、弹出窗口和内联字体或脚本。在只使用 ||bet365.com^ 的情况下，与 EasyList 兼容的语法无法实现上述效果。

这个选项用于禁用一条已有的过滤规则。有时禁用一条已有的过滤规则比创建一条例外规则来得更好。举例来说，一位疏忽的过滤规则列表维护者在其列表里面添加了下面这条规则：

*$image

这下你浏览器里所有网站的图片都被屏蔽了。添加一条例外规则（@@*$image）并不是好的解决办法，因为这也导致本应合法屏蔽的其他图片也被放行了。这时最好的办法是为该规则添加一个 badfilter 选项：

*$image,badfilter

这么做会直接将这条 *$image 过滤规则作废。只要在任意一条静态过滤规则后面添加 badfilter 就可以阻止加载该规则。

从 1.19.0 开始，任何满足以下条件：

• 属于以下形式：|https:// 或 |http:// 或 *，并且
• 含有 domain= 选项，并且
• 在它的domain= 选项中不含用于取消的域名，并且
• 不含 csp 选项，并且
• 不含 redirect= 选项

的规则都将按以下方式进行处理：

• domain= 选项将被分解用来创建尽可能多的单独的过滤规则，这些规则的 domain= 选项都包含单独的值。
• 现在可以把单独的某条规则变成 badfilter，而不是像以前只能把所有规则都变成 badfilter。
• 这些特殊过滤规则的 domain= 选项将始终在记录台里被报告为仅包含一条主机名。

等同于 stylesheet 选项。提供只是为了使用方便。

这是 1.26.0 版本新增的选项。

在例外规则里使用时，可针对当前已指定的文档忽略对 CNAME 解除伪装(uncloaked) 请求的屏蔽。

过滤引擎可以控制用于处理 canonical name（规范名称） 的网络请求。但我们可以通过创建附带 cname 选项的例外规则来跳过它。

示例：

@@*$cname

上述规则告知网络过滤引擎接受满足所有以下条件的网络请求：

• 网络请求已被屏蔽
• 网络请求是非主机别名的请求

除非因没有其他切实可行的解决办法导致维护负担变得更大，过滤规则列表作者应尽可能避免使用 cname 类型的例外规则。这类例外规则生效范围应尽可能缩小，例如只在特定的域名生效，等等。

这是 1.26.0 版本新增的选项。

denyallow 的作用是让静态过滤引擎实现默认拒绝/允许例外（default-deny/allow-exceptionally）的功能。

例如：

*$3p,script,denyallow=x.com|y.com,domain=a.com|b.com

上述过滤规则会告诉网络过滤引擎，对于 a.com 或 b.com 网站，屏蔽除来自 x.com 和 y.com 以外的所有第三方脚本。

请注意 domain= 这个选项必须有！

基本上来说，这个新的 denyallow 选项让静态过滤规则列表实现默认拒绝/允许例外功能变得更容易，而此前还只能通过使用难用的正则表达式[1]，或宽泛的屏蔽规则配上例外规则[2]来做到。

目前还不支持通过“实体” 中的通配符进行匹配。

[1] hg.adblockplus.org/ruadlist/rev/f362910bc9a0

[2] 典型的宽泛屏蔽规则指的是 |http*:// 形式的规则

也可以参见：to

也可写作：doc

这是一个指定网页 主框架（或称为根文档）的 类型 选项，类似于（图片 or 脚本）。该选项在仅指定 URL 的主机部分的规则中自动启用（参见 “HOST 文件”部分），导致规则所匹配的网页被严格屏蔽。

也可参见：all

也可写作：from

该选项可限制过滤规则只在指定域名生效。

使用 | 符号可连接多个域名。

在域名前添加 ~ 表示规则不在此域名生效。

uBO 从 1.28.0 版本开始添加对 “实体” 匹配的支持。你可以添加 filter$domain=google.* 来使规则在指定域名对应所有顶级域名的网页中生效。

示例：

||doubleclick.net^$script,domain=auto-motor-und-sport.de
||adnxs.com^$domain=bz-berlin.de|metal-hammer.de|musikexpress.de|rollingstone.de|stylebook.de
/adsign.$domain=~adsign.no

从 1.46.1b17 版本开始支持基于正则表达式的值。例如： @@*$ghide,domain=/img[a-z]{3,5}\.buzz/

相关的讨论：uBlockOrigin/uBlock-issues#2234

基于正则表达式的域名的值也可以添加 “~” 符号排除匹配，和普通值或基于实体的值一样： *$domain=~/regex.../

也可参见：to

也可写作：ehide

在 uBO 1.23.0 之前的版本该选项会在内部翻译为 generichide。

在例外规则里使用时，该选项可在匹配的页面里禁用所有修饰规则。

等同于 ~third-party 选项。从 0.9.9.0 开始提供，只是为了使用方便。

等同于 subdocument 选项。提供只是为了使用方便。

这是 1.46.1b0 版本新增的选项。

它只是 domain= 选项的别名。记录台在渲染网络规则是会使用 from= 来代替 domain=。

参见：domain

也可写作：ghide

该选项只能用于添加白名单规则，作用是在匹配的页面里禁用 通用 的修饰规则。

通用的修饰规则是指针对所有页面生效的元素隐藏规则，例如 ##.ad-class。

这是 1.32.0 版本新增的选项。而 1.52.3b16 默认已开启该选项^[1]

该选项可根据是否出现特定的响应头部，以及是否匹配特定值，来过滤出网络中的响应。

例如：

*$script,header=via:1.1 google

上述规则可屏蔽这类的网络规则 -- 类型是 script，某一响应的 HTTP 头部名称是 via，响应的值字面上与1.1 google 这个字符串相匹配。

头部的值可以设置为正则表达式，只要包裹在常用的斜杠符号 /.../ 里：

*$script,header=via:/1\.1\s+google/

在头部的值前面添加 ~ 可以取消对其进行匹配：

*$script,header=via:~1.1 google

头部的值是可选的，在只需测试特定头部是否出现时可以不使用头部的值：

*$script,header=via

使用通用的例外规则可以禁用特定的屏蔽 header= 的规则，即 @@*$script,header，它可以覆盖上例中的屏蔽 header= 的规则。

**重要提示：**创建带有 header= 选项的规则时尽可能多使用生效范围精确的其他规则选项，header= 选项最好只在其他选项不足以做到时才使用。

它的潜在使用场景是屏蔽在网站子域名中作为第一方代理的 Google Tag 管理器脚本：

*$1p,strict3p,script,header=via:1.1 google

在这里：

• 连接是网页的“弱”第一方。
• 连接不是网页严格的第一方。
• 连接类型是 script。
• 连接包含一个名为 via 的 HTTP 响应头部，其值与 1.1 google 相匹配。

以下规则用于屏蔽其响应头部是 Set-Cookie，值为任意值的请求：

||example.com^$header=set-cookie 

以下规则用于解除屏蔽其响应头部是 Set-Cookie ，值与 foo, bar$ 这条正则表达式相匹配的请求：

@@||example.com^$header=set-cookie:/foo\, bar\$/ 

如要移除响应的头部，参见：响应头部过滤。

这个 important 选项的作用是忽略所有 白名单 规则（@@ 打头的规则），允许你百分之百屏蔽特定的网络请求。

这个选项只适用于屏蔽请求的网络规则

例如：||google-analytics.com^$important,third-party 会屏蔽所有发送到 google-analytics.com 的网络请求，无视任何已有的 例外 规则。

可通过 CSP 禁用主页面内联脚本标签，例如：||example.com^$inline-script。

也可参见：csp

可通过 CSP 禁用主页面的内联字体标签，例如：||example.com^$inline-font。

这是 1.31.1b8 版本新增的选项。

仅适用于正则表达式规则。其他类型规则使用该选项的话，uBO 会丢弃此规则。

该选项指示 uBO 过滤引擎执行匹配时区分大小写。

这是 1.46.1b0 版本新增的选项。

相关的 issue：uBlockOrigin/uBlock-issues#2117。

允许根据网络请求的 HTTP method 对其进行屏蔽。

该选项支持一系列用 | 分隔且全部为小写字母的 method 名，并支持带否定的 method 名。

以下是所支持的有效名称：

• connect
• delete
• get
• head
• options
• patch
• post
• put

参见 DNR 本身提供的文档:

• https://developer.chrome.com/docs/extensions/reference/declarativeNetRequest/#type-RequestMethod

示例：

||google.com^$method=post|get
||example.com^$method=~get

记录台可显示每个网络请求使用的 method。你可以从记录台的输出日志从筛选出最常用的 method：get, head, post。

这是 1.50.1b16 版本新增的选项。

权限策略提供了一种机制，明确声明什么功能可以或不可以在一个网站上实现。它类似于 Content Security Policy，但它控制的是功能特性，而不是安全行为。

以下提供了一些如何使用权限策略的例子：

• 修改移动网站和第三方视频里关于自动播放的默认行为。
• 限制网站使用敏感设备，如摄像头、麦克风或扬声器。
• 允许 iframes 使用 Fullscreen API。

相关讨论：

• https://github.com/uBlockOrigin/uBlock-issues/discussions/2714

参考文章：

• https://adguard.com/kb/general/ad-filtering/create-own-filters/#permissions-modifier
• https://docs.w3cub.com/http/headers/feature-policy#directives
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy

示例：

||example.com^$permissions=browsing-topics=()

与 AdGuard 的语法不同之处在于：使用 | 分隔多个权限策略，而不是 \, -- uBO 会将 | 替换为 , ：

*$permissions=oversized-images=()|unsized-media=()

然而，最好不要将多个权限策略合并在一起，以免破坏它的例外规则。

在没有指定类型（例如 $doc）的情况下，在使用 permissions 选项时 uBO 会在内部使用 $document,subdocument（同 csp 一样）)。

屏蔽由链接的 ping 属性以及 Navigator.sendBeacon() 发出的请求。

用于屏蔽“背弹式”（popunders）窗口或标签页，背弹式表示原始页面被重定向到一个广告页，目标内容则在另一个新建的页面加载。使用方法和 popup 规则选项一样，只是它是用来屏蔽背弹式窗口。

也可写作：shide

这是 uBO 1.23.0 新增的选项。

在例外规则里使用时，可在匹配的页面禁用 特定 的修饰规则。

特定的修饰规则是仅在指定域名生效的规则，例如 example.com##.ad-class。

这是 1.32.0 版本新增的选项。

该选项表示这是严格的第一方请求。

传统的 1p 选项对于第几方的匹配是“弱”匹配。例如，一条网络请求如果在网页与请求同属一个 基础域名 时就被认为是第一方。

而新增的 strict1p 选项则是对第几方进行严格检查。例如，一条网络请求如果在网页与请求同属一个 主机名 时才被认为是第一方。

例如：

这是 1.32.0 版本新增的选项。

该选项表示这是严格的第三方请求。

传统的 3p 选项对于第几方的匹配是“弱”匹配。例如，一条网络请求仅在网页和请求的 基础域名 不同时才认为是第三方。

而新增的 strict3p 选项则是对第几方进行严格检查。例如，一条网络请求只要网页和请求的 主机名 不同就认为是第三方。

例如：

这是 1.46.1b0 版本新增的选项。

相关的 issue：uBlockOrigin/uBlock-issues#2412。

该选项主要目的是让 uBO 的静态网络过滤引擎拥有等同于 DNR 的 requestDomains 和 excludedRequestDomains 的功能。

to= 是 denyallow= 的超集，支持基于实体的语法和带否定的主机名。

目前 denyallow= 我还不打算放弃使用，但它不支持基于实体的语法，也不支持带否定的主机名。

示例：

||it^$3p,to=~example.it
*$script,from=beforeitsnews.com,to=google.*|gstatic.com

还可以参见：denyallow, from

等同于 xmlhttprequest 选项。提供只是为了使用方便。

该选项用于将额外的 Content-Security-Policy 头部插入到被请求页面的 HTTP 网络响应，让内容安全策略变得更严格，就像规范设计的那样。它仅对文档请求生效。

这类特殊的规则并不屏蔽匹配到的资源，而仅屏蔽网页的 HTTP 头部。因此请与其他指定资源类型的选项结合使用，如 image、script 或 frame (subdocument)。此外它还是可以与 1p (first-party)、3p (third-party) 或 domain 选项结合使用。

csp 规则的实现方式使得它可以应用在某些有趣的场景。例如你可以只屏蔽页面某个特定路径中的脚本：

||example.com/subpage/*$csp=script-src 'none'

甚至可以屏蔽除主页面之外的所有页面脚本（注意那个结尾锚标）：

||example.com/*$csp=script-src 'none'
@@||example.com^|$csp=script-src 'none'

特定 csp 屏蔽规则的例外规则必须包含与原规则完全一样的 csp 选项内容。csp 选项内容为空的例外规则将会禁止匹配页面的所有 csp 插入：

@@||example.com^$csp

相比其他规则，CSP 选项的语法看起来有些与众不同，只建议高级用户使用。它可用在 “allowlist” 模式下，即数据的下载只限于该选项明确指定的地址。不过 uBO 正在加入他自己的第二个 CSP 头部, 按照规范，它会被并入最终的策略，总之就是通过两个头部执行最为严格的规则。例如，如果服务器发送的策略允许 a.com 和 b.com，并且你的规则添加了 c.com，你可以轻松破坏网页的显示。不会有任何请求被允许。

可参考 "Content Security Policy (CSP) Quick Reference Guide" 或 MDN 文档获取进一步的语法帮助。

也可参见 denyallow

这是 1.22.0 版本新增的选项。

empty 规则选项会被 uBO 在内部转换为 redirect=empty，但不同于 redirect 这个选项是明确使用的，empty 不必要求有资源类型。

在使用 empty 时，只有打算返回一个文本响应的网络请求才会被 uBO 重定向到一个空的响应体(response body)，所以 empty 不能用在诸如图片、媒体这样的资源，或其他二进制资源。

也可参见：mp4、redirect

这是 1.22.0 版本新增的选项。

mp4 规则选项会在内部被转换为 redirect=noopmp4-1s，并且假定要求的是 media 这个资源类型。

也可参见：empty](#empty)、redirect

该选项表示 “屏蔽和重定向”，是在内部真实创建两条过滤规则，一条是屏蔽规则，一条是重定向规则（redirect-rule）。

重定向规则用于将被屏蔽的网络请求重定向到一个本地中立资源版本。该中立资源必须使用资源令牌进行引用。你可以使用空的重定向资源和 URL-specific sanitized redirect resources (surrogates)。在运行时，资源令牌未解析处理的规则会被丢弃。

redirect= 规则可与其他静态规则选项一同使用，也可使用 @@ 设为例外规则，也可以添加 badfilter 选项变成被禁用的规则，还可以添加 important 选项提升其优先级。

考虑到多个重定向选项可应用于一条网络请求，于是引入了重定向优先级的概念。

默认情况下，重定向规则隐含的优先级是 0。创建过滤规则时可以明确声明它的优先级，只要在 redirect= 选项的令牌之后附上:[integer](也支持负整数值)。例如：

||example.com/*.js$1p,script,redirect=noopjs:100

该优先级会指出在众多重定向令牌里最终使用哪个令牌。多个 redirect= 选项应用于一条被屏蔽的网络请求的场景不太可能出现。所有重定向选项都会上报至记录台，最终有效的那个选项就是在记录台重定向条目前出现的最后一个选项。请仅在有重定向争议需要解决时才明确规定重定向优先级。

如要禁止重定向，你可以为重定向创建一条例外规则，例如：

@@||example.com/*.js$1p,script,redirect-rule=noopjs

上述规则不影响规则正常屏蔽，只影响重定向部分。如要全部禁止重定向，你可以使用以下规则：

@@||example.com/*.js$1p,script,redirect-rule

该选项从 1.4.0 版本开始使用。

该选项可用来创建单独的重定向规则， 即不具有屏蔽功能。

例如下面这条规则：

    ||example.com/ads.js$script,redirect=noop.js

上述规则其实是一条用于屏蔽 ||example.com/ads.js$script 并满足重定向条件的规则。再看看下面这条：

||example.com/ads.js$script,redirect-rule=noop.js

上述规则不会创建用于屏蔽的规则，只是创建一条重定向的规则。单独用于重定向的规则在屏蔽资源是可选的时候很有用，但我们还是想要资源不管以何种方式被屏蔽 - 是通过单独的一条屏蔽规则还是动态过滤规则或其他方式，都能被重定向。

该选项是从 1.22.0 开始引入的。

这是 1.32.0 版本新增的选项。

该选项用于从网络请求的 URL 移除查询参数--也可参见 AG 的 removeparam文档。出于历史原因考虑，queryprune 等同于 removeparam（避免使用 queryprune，它目前已被放弃使用，最后也会被移除）。

removeparam 是一个修改符选项（比如 csp），它并不会导致网络请求被屏蔽，而是在被忽略之前进行修改。

removeparam 的值可以是一条正则表达式，此时 uBO 将移除与正则表达式匹配的查询参数：

*$removeparam=/^utm_/

上述规则会移除所有名字以 utm_ 打头的查询参数，无论其值是什么。在使用正则表达式时，每条查询参数的名称-值这一对会被合并成单独的 name=value 字符串后再次测试。

糟糕的 removeparam 规则会对性能有负面影响。经验丰富的规则作者应该要了解如何创建精良的规则。

已修饰规则形式添加的参数无法通过 removeparam 进行移除（参见相关的评论：760#issuecomment-724703650 以及无效的 issues：#1704、#1767、#1951、#2498）

也可参见：过滤规则性能

仅在可信任来源的域名使用。

参见 https://adguard.com/kb/general/ad-filtering/create-own-filters/#replace-modifier

[文档尚在完善]

仅在可信任来源的域名使用。

将一条 URL 的路径/查询/哈希部分进行转换。

[文档尚在完善]

静态扩充规则包括下面两种形式：

[主机名]##[表达式]
[主机名]#@#[表达式]

静态扩充规则的最常见类型是修饰规则，也就是俗知的 ABP “元素隐藏规则”。

所有静态扩充规则都可只在特定的 实体（Entity）生效，例如：

google.*###tads.c

所谓 实体 的定义是一个正式的域名，其公用后缀（Public Suffix）部分用通配符来代替。

例如：google.* 会对所有类似的 Google 域名生效，像是 google.com、google.com.br、google.ca、google.co.uk 等域名。再比如：facebook.* 会对所有类似的 Facebook 域名生效，像是 facebook.com、facebook.net。

由于基础域名用于派生出“实体”，所以 google.evil.biz 不匹配 google.*。

这是 1.25.0 版本新增的规则。

相关的 issue：uBlockOrigin/uBlock-issues#803。

在一条典型的通用修饰规则前添加*，可以将其转化为一条特定的通用修饰规则，它会无条件插入所有网页：

*##.selector

但一条典型的通用修饰规则仅在 uBO 的 DOM 测量器发现网页里至少有一个匹配的元素时才插入网页。

##.selector

新的 specific-generic 形式规则也会在网页匹配 generichide 例外规则时被禁用，这是由于它基本上就是一条通用规则 -- 和普通的通用形式不同之处在于它是无条件插入，而不是通过 DOM 测量器。

勾选“规则列表”版块中的“忽略通用元素过滤规则”选项后，Specific-generic 修饰规则不会被忽略，原因是该选项主要目的是禁止 DOM 测量器运作。

:has(...), :has-text(...), :matches-attr(...), :matches-css(...), :matches-css-before(...), :matches-css-after(...), :matches-media(...), :matches-path(...), :min-text-length(n), :not(...), :others(...), :upward(...), :watch-attr(...), :xpath(...)。

具体请参见这篇文档。

默认情况下，修饰规则的隐含作用是隐藏无用的 DOM 元素。但它也可以帮助修改特定元素的样式，或者完全从 DOM 树删除。

• 描述：动作操作符 ，用于指示 uBo 从 DOM 树移除元素，而不仅仅是隐藏。
• 是否可链接：否，动作操作符 只能应用在根链（root chain）的末端。
• subject：可以是一个普通的 CSS 选择符，也可以是一条过程式修饰规则。
• 示例：
  • gorhill.github.io###pcf #a18 .fail:remove()

这是 uBO 1.26.0 版本新增的，修复了 #2252。

由于 :remove() 是一个“动作”操作符，它只能用作 trailing operator（就像是 :style() 操作符).

AG 的修饰规则语法 { remove: true; } 会在内部被转换为 uBO 的 :remove() 操作符。

如要在浏览器解析_之前_ 就从文档移除元素，请参见：HTML 规则。

• 描述：动作操作符 ，将指定的样式应用到 DOM 树中选中的元素。
• 是否可链接：否，动作操作符 只能应用在根链的末端。
• subject:1.29.3b10 版本开始可以是一个普通的 CSS 选择符，也可以是一条过程式修饰规则。之前的版本仅支持原生、普通的 CSS 选择符，参见 #382。
• arg: 一条或多条 CSS 属性声明，之间用标准的 ; 符号分隔。部分字符、字符串和值被禁止使用，具体参见以下列表。
• 示例：
  • example.com##h1:style(background-color: blue !important)
  • motobanda.pl###mvideo:style(z-index: 1 !important)

从 1.29.3b10 版本开始支持过程式选择符。

相关的 issue：支持带有明确 style 属性的修饰规则 以及有帮助的示例。

这条规则的语法和普通的修饰规则的语法（即必须是一个有效的 CSS 选择符）是一样的，除了在末尾加了一个 :style(...) 后缀。括号里面必须是一条或多条 CSS 属性声明（之间用标准的 ; 符号分隔）。规则的属性值不允许使用 url(...)，否则这样的 style 规则会被丢弃。不允许使用：

• 带有 url(...) 的属性值，
• 带有 image-set(...)的属性值，
• 注释：（/*、*/），
• 反斜杠符号（\的 escaped 值），
• 双斜杠符号（//），包括中间被空格分隔

诸如此类基于 style 的修饰规则将被丢失。

和其他新增的修饰规则选择符一样，:style 选择符只能用在 具体 的修饰修饰规则里，即规则必须指定一个主机名或实体。

uBO 可透明转换并使用 AG 的 CSS 插入规则。这基本上意味着如果喜欢的话你可以在 uBO 使用 AG 的语法。

样式规则常常是用来阻止网页中反过滤工具机制生效的。为此，你可能会需要用到 AG 的过滤规则列表，它可以在第三方规则列表版块启用。

• 描述：动作操作符，用于从 DOM 树的节点移除属性或 class，而不仅仅是隐藏。
• 是否可链接：否，动作操作符 只能应用在根链的末端。
• subject：可以是一个普通的 CSS 选择符，也可以是一条过程式修饰规则。
• arg：一个完全匹配的普通字符串，或一条正则表达式。如果解析器无法正确解析 arg，请将 arg 用括号括起来，这主要发生在使用特殊字符时。
• 示例
  • userscloud.com##.btn-icon-stacked[onclick]:remove-attr(onclick)
  • magesy.*,majesy.*##[oncontextmenu]:remove-attr(oncontextmenu)
  • zerodot1.gitlab.io##selector:remove-attr(/oncontextmenu|onselectstart|ondragstart/)
  • zerodot1.gitlab.io##selector:remove-attr(/^on[a-z]+/)
  • danskebank.fi##html[cookie-consent-banner-open]:remove-class(cookie-consent-banner-open)

这是从 uBO 1.45.3b13 开始引入的。

这两个新增的伪选择符均是 动作 操作符，因此只能在选择符的末端使用。它们都可以当作是一个字符串或正则表达式形式的 arg 参数。

对于 :remove-class()，一旦参数匹配到相应的 class 名，该 class 名将被移除。

对于 :remove-attr(), 一旦参数匹配到相应的属性名，该属性名将被移除。

这两个操作符原本是用来替换 +js(remove-attr, ...) 和 +js(remove-class, ...) 这两个今后要被放弃使用的候选选项。

也可参见：:watch-attr() 的使用场景，即目标属性被添加时 DOM 布局不发生变化。

支持 Firefox 57+ 的 uBO 1.15.0+ 版本。

请仔细阅读： HTML 过滤的作用对象是响应数据（在浏览器解析前）。请不要使用开发工具里的浏览器查看器创建 HTML 规则。你必须 使用 view-source:[页面 URL]查看这些响应数据以便找到用于创建对应 HTML 规则的有关信息。

使用 HTML 规则时文档中的元素在被浏览器解析前就已移除。

其语法与修饰规则类似，除了在选择符（CSS 或过程式）前面必须添加一个 ^ 符号：

example.com##^.badstuff
example.com##^script:has-text(7c9e3a5d51cdacfc)

这些 HTML 规则会将与选择符相匹配的元素从流响应数据中移除，浏览器解析被修改过的响应数据时将再也感知不到这些元素的存在。这使得 HTML 规则成为 uBO 又一强大的武器。

HTML 过滤仅在文字编码格式兼容 UTF-8、ISO-8859-1、Windows-1250、Windows-1251 和 Windows-1252（详细映射方式）的页面生效。

从 1.48.5b4 版本开始，你可以在 HTML 规则里使用 “~” 排除域名。例如：

google.com,~translate.google.com##^script:has-text(consentCookiePayload)

也可参见：remove-node-text

这是 uBO 1.35.0 新增的语法。

它用于移除响应的头部，是一种特殊场景的 HTML 过滤方式，针对的是响应的头部，而不是响应的本体（body）：

example.com##^responseheader(header-name)

这里的 header-name 必须为小写字母，它是要移除的头部的名称。

移除响应头部的功能仅针对文档资源本身生效，如主文档或子框架。

可移除的头部仅包括以下几种：

• location
• refresh
• report-to
• set-cookie

这个限制是为了确保 uBO 不会因此降低网页配置的安全性，即不会移除 content-security-policy。

考虑到移除头部是在 onHeaderReceived 时候发生的，这项新特性适用于所有浏览器。

添加这项新特性是因为我发现有的网站使用 refresh 头部，在几秒后将访客重定向到他们不想访问的网站。

根据是否存在特定的响应头部以及它是否匹配不同的值来屏蔽网络响应。参见：header。

example.com##+js(...)

该规则允许在页面里插入特定的 Javascript 代码。... 部分表示要识别的 Javascript 资源的标志（token），该资源来自资源库。请记住该资源库完全由 uBO 项目掌控，只有被 uBO 担保过的 Javascript 代码才允许嵌入到页面里，且必须使用一个有效的资源标志。

部分小脚本支持额外的参数，可在小脚本名后面指定，用逗号分隔。参数里面的逗号必须要转义。在 1.22.0 之前的版本只支持在正则表达式 (/foo\x2Cbar\u002Cbaz/) 里使用，但现在有一个反斜杠符号就够了 (foo\,bar)。

如果是通用的 +js 规则，则会被忽略：这类规则必须是专门使用的，例如必须在特定的主机名下才可生效，像是 example.com##+js(nobab) 会将 bab-defuser 插入到 example.com 域名下的页面。

从 1.22.0 版本开始，uBO 添加对新的例外规则语法的支持，可完全禁止在特定站点的插入小脚本，而不必为所有匹配的小脚本插入规则都创建例外规则。

以下例外规则可完全禁止在 example.com 插入小脚本：

example.com#@#+js()

或所有地方都禁止插入小脚本：

#@#+js()

以下形式的规则没有意义，会被直接忽略：

example.com##+js()