匹配模式

此页面由 docs/pattern.md 自动同步生成。

匹配器

pattern 是 Bifrost 规则中的第一部分，用于匹配请求 URL。

Pattern 类型

Bifrost 支持五种 Pattern 类型，系统会按以下顺序自动检测：

类型	触发条件	优先级范围
Regex	以 / 开头且以 /、/i、/u、/iu 结尾	80
PathWildcard	以 ^ 开头	60-70
IP	符合 IPv4/IPv6/CIDR 格式	70-95
Wildcard	包含 *、? 或以 $ 开头	40-60
Domain	默认类型	100-133+

所有类型均支持 ! 前缀表示否定匹配。

Domain 匹配

精确匹配域名、端口和路径。

格式

[protocol://]domain[:port][/path]

协议匹配

格式	说明
http://	仅匹配 HTTP
https://	仅匹配 HTTPS
ws://	仅匹配 WebSocket
wss://	仅匹配 WSS
tunnel://	仅匹配隧道代理
http*://	匹配 HTTP 和 HTTPS
ws*://	匹配 WS 和 WSS
//	匹配所有协议
无协议	匹配所有协议

端口通配符

格式	示例	说明
*	example.com:*	匹配任意端口（必须有端口）
8*	example.com:8*	匹配以 8 开头的端口
*80	example.com:*80	匹配以 80 结尾的端口
8*8	example.com:8*8	匹配 88、808、8008 等

路径匹配

格式	说明
/path	匹配该路径及其子路径
/path/*	匹配该路径前缀

示例：

example.com/api              # 匹配 /api、/api/users、/api?q=1
example.com/api/*            # 匹配 /api/ 开头的所有路径
https://example.com:8443/api # 完整匹配

ℹ️ 含 * 的 example.com/api/* 在类型检测时会被归类为 Wildcard（优先级约 60），而非 Domain。只有裸 /path 前缀形式（如 example.com/api）才保持为 Domain 模式。这里仅描述其运行时匹配行为（命中 /api/users、/api/，但不命中裸 /api）。

IP 匹配

匹配 IP 地址或 CIDR 网段。

格式	示例	说明
IPv4	192.168.1.1	精确 IP
IPv6	::1、2001:db8::1	精确 IP
CIDR	192.168.0.0/16、10.0.0.0/8	网段匹配

Wildcard 匹配

域名通配符匹配，自动识别包含 *、? 或以 $ 开头的 pattern。

通配符

通配符	说明	示例
*	匹配单级（不含 .）	*.example.com 匹配 www.example.com，不匹配 a.b.example.com
**	匹配多级（含 .）	**.example.com 匹配 a.b.c.example.com
?	匹配单个字符	example?.com 匹配 example1.com
$	域名通配符前缀	$example.com 匹配 http(s)://example.com 及其路径

示例

*.example.com                # 单级子域名
**.example.com               # 多级子域名
*example*                    # 包含 example
example.*/api/*              # 域名后缀 + 路径
$*.example.com               # 域名通配符，匹配单级子域名的所有路径
$**.example.com              # 域名通配符，匹配多级子域名的所有路径

⚠️ 不要在 Wildcard 模式前加协议前缀。协议前缀（http://、https://、http*://、ws*://、//）只对 Domain 和 PathWildcard（^ 前缀）模式可靠；与 Wildcard 模式组合会出现以下错误行为：

写法	实际行为
*.example.com（裸写，推荐）	正确匹配单级子域名（HTTP + HTTPS）
http://*.example.com / https://*.example.com	能匹配，但单星 * 会跨越 .，等价于 **（丢失单级限制）
http*://*.example.com / ws*://*.example.com	永不匹配（静默失效）
//*.example.com	匹配所有 host（过度匹配，等价于无差别命中，存在误伤风险）

需要按协议限定时：裸 Wildcard 已覆盖 HTTP/HTTPS；要限定单一协议或匹配 WS/WSS，请改用 Domain 模式（如 http*://api.example.com）或 PathWildcard（如 ^http*://example.com/api/*）。

PathWildcard 匹配（^ 前缀）

路径通配符匹配，以 ^ 开头显式声明。支持三种级别的通配符：

通配符	正则等价	说明
*	[^?/]*	单级路径（不含 / 和 ?）
**	[^?]*	多级路径（不含 ?）
***	.*	任意字符（含 / 和 ?）

示例

^example.com/api/*/info      # 匹配 /api/users/info，不匹配 /api/a/b/info
^example.com/api/**          # 匹配 /api/a/b/c，不匹配 /api/a?q=1
^example.com/api/***         # 匹配任意内容，包括 /api/a/b?q=1

Regex 匹配

正则表达式匹配，语法与 JavaScript 正则兼容。

格式

/pattern/[flags]

Flags

Flag	说明
i	大小写不敏感
u	Unicode 模式

示例

/\.example\.com/             # 匹配 .example.com
/api\/v\d+/i                 # 大小写不敏感匹配
/测试/u                      # Unicode 匹配

否定匹配

所有类型均支持 ! 前缀表示否定：

!example.com                 # 排除 example.com
!192.168.0.0/16              # 排除内网 IP
!*.internal.com              # 排除 internal.com 子域名
!/\.test\./                  # 排除包含 .test. 的 URL

子匹配传值

Wildcard、PathWildcard 和 Regex 支持捕获组，通过 $1-$9 引用：

Wildcard 传值

*.example.com file:///data/$1        # $1 = 子域名
example.*/api/* file:///mock/$1/$2   # $1 = TLD, $2 = 路径

PathWildcard 传值

^example.com/api/*/info file:///mock/$1.json   # $1 = 单级路径
^example.com/*/*       file:///data/$1/$2      # $1, $2 = 各级路径

Regex 传值

/api\/v(\d+)\/users\/(\d+)/ reqHeaders://X-Version=$1 reqHeaders://X-ID=$2

reqHeaders:// 不以 & 拆分多个 header：写成 reqHeaders://X-Version=$1&X-ID=$2 只会设置单个请求头 X-Version: <值>&X-ID=<值>（&X-ID=... 成为值的一部分）。要设置多个 header，请用多个独立的 reqHeaders:// 操作（如上例），详见 operation.md。

优先级

规则按优先级从高到低匹配：

类型	优先级	说明
Domain（完整）	≥130	100 基础 +5 协议 +10 端口 +（15+路径段数）精确路径
Domain（基础）	100	仅域名
IP（精确）	95	单个 IP
Regex	80	正则表达式
IP（CIDR）	70-78	按前缀长度
PathWildcard	60-70	* > ** > ***
Wildcard	40-60	按类型

配置示例

域名匹配

example.com proxy://127.0.0.1:8080
http*://api.example.com cache://3600
example.com:8*/api/* file:///mock

上例第三行的 example.com:8*/api/* 是裸 Wildcard，不要写成 //example.com:8*/api/*：// 前缀与 Wildcard 组合会匹配所有 host（见上文 Wildcard 协议前缀说明）。

IP 匹配

192.168.1.1 proxy://127.0.0.1:3000
10.0.0.0/8 reqHeaders://X-Matched-Private=1
!192.168.0.0/16 proxy://external

通配符匹配

*.example.com proxy://127.0.0.1:8080
**.cdn.example.com cache://86400
$api.example.com file:///mock

路径通配符匹配

^example.com/api/*/info file:///mock/$1.json
^example.com/static/** cache://3600
^api.example.com/v*/users/*** reqHeaders://X-Api-Pattern=path-wildcard

正则匹配

/^https?:\/\/.*\.example\.com/ proxy://127.0.0.1:8080
/\/api\/v(\d+)\// reqHeaders://X-Version=$1
/\.(jpg|png|gif)$/i cache://86400

扩展阅读

• 规则语法文档：了解完整的规则语法结构
• 操作指令文档：学习如何配置操作指令
• 规则协议手册：按协议查看各能力说明与示例