运行操作

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

操作符/operation

在 Bifrost 中，每条规则由 匹配模式（pattern） 和 操作（operation） 两部分组成，操作的通用语法为：

protocol://[value]

protocol：指定操作类型（如 file、proxy、resHeaders 等）
value：操作内容（支持多种格式，见下文）

Value 类型

Bifrost 会根据 value 的格式自动识别其类型，支持以下 6 种：

类型	格式	示例	说明
内联值	普通字符串	`127.0.0.1:8080`	直接作为操作内容
内联参数	`key=value&...`	`x-proxy=Bifrost&x-test=1`	自动解析为键值对
小括号内容	`(content)`	`({"ec":0})`	括号内容直接作为操作内容
Values 引用	`{key}`	`{config.json}`	引用 Values 中的内容
本地文件	`/path/to/file`	`/Users/xxx/mock.json`	从本地文件加载内容
远程资源	`http(s)://url`	`https://example.com/data.json`	从远程 URL 加载内容

⚠️ 重要：内联值、内联参数、小括号内容这三种类型的 value 不能包含空格。规则解析器使用空格分隔多个操作符，value 中的空格会导致解析错误。如需使用包含空格的复杂内容，请使用 Values 引用、本地文件 或 远程资源。

识别规则

Value 按以下优先级进行识别：

以 http:// 或 https:// 开头 → 远程资源
以 / 开头（非 //）→ 本地文件
以 ( 开头且以 ) 结尾 → 小括号内容
以 { 开头且以 } 结尾 → Values 引用
包含 = 且不含 / 和 { → 内联参数
其他情况 → 内联值

内联值

直接将 value 作为操作内容：

pattern reqHeaders://x-proxy=Bifrost       # 设置单个请求头
pattern statusCode://404                   # 修改状态码
pattern host://127.0.0.1:8080              # 转发到指定地址

⚠️ 值不能包含空格，空格会被解析器识别为操作符分隔符，导致规则解析错误。

内联参数

当 value 符合 key=value&key2=value2 格式时，会自动解析为键值对：

pattern reqHeaders://X-Custom=test&X-Another=value
pattern reqCookies://session=abc123&user=test

解析规则：

以 & 分隔多个键值对
以 = 分隔键和值
键为空时忽略该对
值可以为空（如 flag=）

⚠️ 值不能包含空格，空格会被解析器识别为操作符分隔符，导致规则解析错误。

小括号内容

当操作内容需要包含特殊字符（如 /、{）时，使用小括号包裹可避免被误识别：

pattern file://({"ec":0,"data":null})      # JSON 作为响应内容
pattern reqHeaders://(/User/xxx/yyy.txt)   # 将路径字符串作为请求头值

注意：reqHeaders:///User/xxx/yyy.txt 会从文件加载内容，而 reqHeaders://(/User/xxx/yyy.txt) 会将 /User/xxx/yyy.txt 字符串直接设为请求头值

⚠️ 值不能包含空格，空格会被解析器识别为操作符分隔符，导致规则解析错误。如需包含空格或其他复杂内容，请使用 Values 引用。

Values 引用

通过 {key} 格式引用 Bifrost Values 模块中存储的内容：

pattern file://{mockResponse}              # 引用名为 mockResponse 的值
pattern resHeaders://{customHeaders}       # 引用名为 customHeaders 的值

Values 存储机制

Values 以文件形式存储在 Bifrost 数据目录的 values/ 子目录中，每个 key 对应一个 .txt 文件。

创建/编辑 Values：

在 Bifrost 界面的 Values 模块中创建或编辑
在规则中通过 {key} 引用

内嵌值

除了在 Values 模块中预先创建，也可以在规则文件中直接定义内嵌值：

``` ua.txt
Mozilla/5.0 (iPhone; CPU iPhone OS 16_6 like Mac OS X)
```
pattern ua://{ua.txt}

内嵌值的 key 需要包含文件扩展名（如 .txt、.json），以便与普通变量区分。

文件/远程资源

从本地文件或远程 URL 加载操作内容：

pattern reqHeaders:///Users/xxx/headers.txt           # 从本地文件加载
pattern resHeaders://https://example.com/config.json  # 从远程 URL 加载

⚠️ 注意：部分协议（如 http、https、ws、wss、host、enable、cache 等）禁止通过文件路径或远程 URL 获取内容，详见各协议文档。

模板字符串

Bifrost 支持类似 ES6 的模板字符串功能，在 value 中动态引用请求信息。使用反引号 ` 包裹的内容会启用模板解析。

基本语法

pattern protocol://`...${variable}...`

支持的变量

基础信息

变量	说明
`${now}`	当前时间戳（毫秒）
`${random}`	0-1 之间的随机小数
`${randomUUID}`	随机 UUID
`${randomInt(n)}`	0 到 n 之间的随机整数
`${randomInt(n1-n2)}`	n1 到 n2 之间的随机整数
`${version}`	Bifrost 版本号
`${id}` / `${reqId}`	请求唯一标识符

URL 相关

变量	说明
`${url}`	完整请求 URL
`${host}`	主机名（可能含端口）
`${hostname}`	主机名（不含端口）
`${port}`	端口号
`${path}`	路径（含查询字符串）
`${pathname}`	路径（不含查询字符串）
`${search}`	查询字符串（含 `?`）
`${query}`	查询字符串（不含 `?`）
`${query.xxx}`	查询参数 xxx 的值
`${queryString}` / `${searchString}`	查询字符串，空时返回 `?`

网络信息

变量	说明
`${method}`	请求方法
`${clientIp}` / `${ip}`	客户端 IP
`${clientPort}`	客户端端口
`${serverIp}`	服务端 IP
`${serverPort}`	服务端端口
`${remoteAddress}`	远程地址
`${remotePort}`	远程端口
`${statusCode}` / `${status}`	响应状态码

Headers 和 Cookies

变量	说明
`${reqHeaders.xxx}` / `${reqH.xxx}`	请求头字段 xxx 的值
`${resHeaders.xxx}` / `${resH.xxx}`	响应头字段 xxx 的值
`${reqCookies.xxx}`	请求 cookie xxx 的值
`${resCookies.xxx}`	响应 cookie xxx 的值

其他

变量	说明
`${env.xxx}`	环境变量 xxx 的值
`${realHost}`	Bifrost 监听的网卡 IP
`${realPort}`	Bifrost 端口号
`${realUrl}`	实际请求 URL

高级用法

URL 编码

使用双花括号语法对变量值进行 URL 编码：

pattern redirect://`https://example.com?url=${{url}}`

转义

使用 $${} 阻止变量展开：

pattern file://`$${host}`   # 输出字面量 ${host}

字符串替换

支持对变量值进行替换操作：

# 简单替换
${hostname.replace(example,test)}     # example.com → test.com

# 正则替换（首次匹配）
${hostname.replace(/\./,-)}           # example.com → example-com

# 正则全局替换
${hostname.replace(/\./g,-)}          # a.b.c.d → a-b-c-d

# 忽略大小写
${hostname.replace(/ABC/i,xyz)}

模板与 Values 结合

模板字符串可以与 Values 引用结合使用：

``` response.json
{"host":"${hostname}","path":"${path}","time":${now}}
```
pattern file://`{response.json}`

访问 https://www.test.com/api/users 时返回：

{ "host": "www.test.com", "path": "/api/users", "time": 1752301623295 }

捕获变量

在正则匹配模式中，可以使用 $1、$2 等引用捕获组：

/api\/v(\d+)\/(.*)/ redirect://`https://api-v$1.example.com/$2`

数据对象格式

部分协议的 value 需要是键值对数据，Bifrost 支持以下格式：

JSON 格式

{
  "key1": "value1",
  "key2": "value2"
}

行格式

key1: value1
key2: value2
key3:value3

解析规则：

优先以 : （冒号+空格）分隔
没有冒号+空格时，以第一个冒号分隔
没有冒号时，value 为空字符串

多级嵌套：

a.b.c: 123
c\.d\.e: abc

等价于：

{
  "a": {
    "b": {
      "c": 123
    }
  },
  "c.d.e": "abc"
}

内联参数格式

key1=value1&key2=value2&keyN=valueN

建议对 key 和 value 进行 encodeURIComponent 编码

协议别名

部分协议支持别名，以下是常用别名映射：

别名	实际协议
`hosts`	`host`
`ignore`	`passthrough`
`status`	`statusCode`
`download`	`attachment`
`html`	`htmlAppend`
`js`	`jsAppend`
`css`	`cssAppend`
`http-proxy`	`proxy`
`h3`	`http3`
`pathReplace`	`urlReplace`
`reqMerge`	`params`

操作协议

每个协议对应一种特定的操作类型，用于对匹配的请求进行相应处理。协议分为以下几类：

控制类

tlsIntercept、tlsPassthrough、passthrough、delete、skip

请求修改类

reqHeaders、reqBody、reqPrepend、reqAppend、reqCookies、reqCors、reqDelay、reqSpeed、reqType、reqCharset、reqReplace、method、auth、ua、referer、urlParams、params

响应修改类

resHeaders、resBody、resPrepend、resAppend、resCookies、resCors、resDelay、resSpeed、resType、resCharset、resReplace、statusCode、cache、attachment

路由类

host、xhost、http、https、http3、ws、wss、proxy、redirect、file、tpl、rawfile

`http3`

启用命中请求的上游 HTTP/3 尝试。该协议没有 value，写法如下：

chatgpt.com http3://
api.example.com h3://

说明：

默认不会主动尝试上游 H3，只有命中 http3:// 或 h3:// 规则才会启用
该能力控制的是“代理到目标服务”的上游协议选择，不是开启下游 UDP/QUIC 监听
仅对 HTTPS 上游请求生效
如果目标不支持 H3 或协商失败，会回退到现有的 HTTP/1.1 或 HTTP/2 转发链路

内容注入类

htmlAppend、htmlPrepend、htmlBody、jsAppend、jsPrepend、jsBody、cssAppend、cssPrepend、cssBody