配置参考

简体中文

English

简体中文

English

外观

[Script] 扩展脚本 ​

本节用于配置 JavaScript 脚本，在 DNS 解析、规则匹配、HTTP 请求/响应处理、定时任务、网络事件或手动调用中执行自定义逻辑。

系统支持以下七种触发类型：

  • HTTP 请求（http-request）：在请求发送至上游服务器前触发。脚本可读取或修改 URL、请求头与请求体，或直接返回自定义响应。
  • HTTP 响应（http-response）：在上游响应返回客户端前触发。脚本可读取或修改状态码、响应头及响应体。
  • DNS（dns）：由 [Host] 的 script:名称 调用，通过 $domain 返回地址或上游 DNS。
  • 规则（rule）：由 [Rule] 的 SCRIPT,名称,策略 调用，通过 $request 返回 {matched: true/false}。
  • 通用（generic）：仅按名称手动调用，控制 API 为 POST /scripts/evaluate。
  • 定时任务（cron）：基于 Cron 表达式周期性触发执行。
  • 网络事件（event）：在系统网络环境或默认网络接口发生变动时触发执行。

HTTPS 流量需先在 MITM 中配置解密，明文报文方可交由脚本处理。

语法声明 ​

本章节采用键值行配置语法。每行声明一个命名的脚本实例，参数之间以逗号分隔：

ini
[Script]
# 通用结构
name = type=..., script-path=..., [options...]

# HTTP 请求脚本
name = type=http-request, pattern=..., script-path=..., [requires-body=...], [max-size=...], [binary-body-mode=...], [options...]

# HTTP 响应脚本
name = type=http-response, pattern=..., script-path=..., [requires-body=...], [max-size=...], [binary-body-mode=...], [options...]

# 定时调度脚本
name = type=cron, cronexp=..., script-path=..., [options...]

# 网络事件脚本
name = type=event, event-name=..., script-path=..., [options...]

# DNS 与规则脚本，由 Host 或 Rule 引用
name = type=dns, script-path=..., [options...]
name = type=rule, script-path=..., [options...]

# 通用脚本，省略 type 时同样使用 generic
name = type=generic, script-path=..., [options...]

行内结构拆解如下：

  • name：脚本在配置文件内的唯一标识符，使用英文字母、数字、下划线或连字符命名。
  • =：键值分隔符。
  • type：脚本触发类型。
  • script-path：脚本资源的本地路径或远程获取地址。
  • 选项参数：根据不同脚本类型按需追加的配置项，采用 key=value 形式书写。

通用配置项 ​

以下选项适用于所有脚本类型：

  • type（枚举值，默认 generic） 脚本的触发类型，决定生命周期与执行时机。可选 http-request、http-response、dns、rule、generic、cron、event。
  • script-path（本地文件路径或 HTTPS URL，必填） 脚本文件的存储位置。支持相对路径、绝对路径或 HTTPS 远程资源地址。
  • script-update-interval（正整数，单位：秒，未设置） 用于 HTTPS 远程脚本地址，设定后台定时自动更新脚本的时间周期。
  • timeout（正整数 1–86400，单位：秒，默认值 5） 脚本单次执行的最长超时时限，有效范围为 1–86400 秒（最大 24 小时）。
  • debug（布尔值，默认值 false） 开启后在调试日志中输出脚本运行细节与执行耗时。
  • argument（字符串，未设置） 传递给脚本执行环境的静态参数，脚本中可通过全局环境读取该字符串。
  • engine（枚举值，默认值 auto） JavaScript 执行引擎，可选 auto、quickjs、webview。auto 模式下：http-request 与 http-response 使用 WebView 引擎；dns、rule、generic、cron 与 event 使用 QuickJS 引擎。

脚本类型专用配置 ​

HTTP 脚本专用配置（http-request / http-response） ​

当 type 为 http-request 或 http-response 时，脚本拦截特定 URL 的网络事务：

  • pattern（正则表达式字符串，必填） 匹配目标请求完整 URL 的正则表达式。
  • requires-body（布尔值，默认值 false） 控制是否截获并向脚本传递完整的 HTTP 报文主体（Body）。
  • max-size（整数，单位：字节，默认值 131072 / 128 KB） 允许截获的最大报文体尺寸。填入正整数限定具体字节数；填入负数（如 -1）表示不设报文体上限。
  • binary-body-mode（布尔值，默认值 false） 控制以二进制字节序列（如 Uint8Array）形式向脚本提供报文主体。

定时脚本专用配置（cron） ​

当 type 为 cron 时，脚本按预定时间节拍运行：

  • cronexp（表达式字符串，必填） Cron 调度表达式，支持 5 段或 6 段标准格式；包含空格时请使用成对的单引号或双引号包裹。

网络事件专用配置（event） ​

当 type 为 event 时，脚本监听系统层级的网络环境变化：

  • event-name（枚举值，必填） 监听的网络状态事件名称，固定为 network-changed。系统网络接口、默认路由或连通状态发生变动时触发。

配置示例 ​

基础配置 ​

ini
[Script]
# HTTP 请求脚本
SignRequest = type=http-request, pattern=^https?://api\.example\.com/v1/trade, script-path=./scripts/sign.js, requires-body=true, timeout=10

# HTTP 响应脚本
DecryptResponse = type=http-response, pattern=^https?://api\.example\.com/v1/data, script-path=https://resource.example.com/scripts/decrypt.js, script-update-interval=86400, requires-body=true

# 定时任务脚本
HealthCheck = type=cron, cronexp="0 */2 * * *", script-path=./scripts/cron_check.js, timeout=30

# 网络事件脚本
NetworkWatcher = type=event, event-name=network-changed, script-path=./scripts/network_event.js

DNS、规则与通用脚本 ​

ini
[Script]
resolver = type=dns,script-path=./scripts/resolver.js
judge = type=rule,script-path=./scripts/judge.js
manual = script-path=./scripts/manual.js,argument=example

[Host]
example.com = script:resolver

[Rule]
SCRIPT,judge,DIRECT
FINAL,DIRECT

DNS 脚本使用 $done({addresses:["192.0.2.1"],ttl:60}) 返回地址；$done({}) 回落普通解析。规则脚本使用 $done({matched:$request.hostname === "example.com"}) 决定是否命中当前规则，策略由规则行指定。通用脚本不自动执行，控制 API 按名称调用时 $trigger 为 http-api；结果通过 $done(value) 返回。