【译】Surge 脚本

脚本需要 Surge iOS 4 或 Surge Mac 3.3.0

您可以根据需要使用 JavaScript 来扩展 Surge 的功能。

脚本区块

[Script]
script1 = type=http-response,pattern=^http://www.example.com/test script-path=test.js,max-size=16384,debug=true
scropt2 = type=cron,cronexp="* * * * *",script-path=fired.js
scropt3 = type=http-request,pattern=^http://httpbin.org script-path=http-request.js,max-size=16384,debug=true,requires-body=true
scropt4 = type=dns,script-path=dns.js,debug=true

每行有两个组成部分：脚本名称和参数。

常用参数：

• type：脚本类型

  • http-request

  • http-response

  • cron

  • event

  • dns

  • rule

• script-path：脚本的路径，可以是配置文件的相对路径、绝对路径或 URL。

• script-update-interval：使用脚本路径的 URL 时的更新间隔，以秒为单位。

• debug：启用调试模式。 脚本每次在评估之前从文件系统加载。

• timeout：脚本的最长运行时间。 默认值为 10 秒。

• argument：脚本可以使用 $argument 获取值。

http-request 和 http-response 的参数：

• pattern：匹配 URL 的正则表达式模式。
• requires-body：允许脚本修改请求/响应体。 默认值为假。 这种行为代价高昂。 仅在必要时启用。
• max-size：请求/响应主体的最大允许大小。 默认值为 131072 (128KB)。
• binary-mode：仅适用于 iOS 15 和 macOS。 原始二进制正文数据将通过 Uint8Array 而不是字符串值传递给脚本。

脚本编写需要 Surge 将整个响应正文数据加载到内存中。 巨大的响应体可能会导致 Surge iOS 崩溃，因为 iOS 系统限制了 Network Extension 可以占用的最大内存量。

请只为必要的 URL 启用脚本。

如果响应正文大小超过 max-size 值，Surge 回退到直通模式并跳过此请求的脚本。

基本约束

脚本允许异步操作。 应该调用 $done(value) 来指示完成，即使对于不需要结果的脚本也是如此。 否则，脚本会因为超时而收到警告。

性能

您无需担心脚本的性能。 JavaScript 核心非常有效。

公共 API

基础信息

• $network

该对象包含网络环境的详细信息。

• $script
  • $script.name<String>：正在执行的脚本名称。
  • $script.startTime<Date>: 当前脚本开始的时间。
  • $script.type<String>: 当前脚本的类型。
• $environment
  • $environment.system<String>: iOS 或 macOS.
  • $environment.surge-build<String>：Surge 的内部版本号。
  • $environment.surge-version<String>：Surge 的短版本号。
  • $environment.language<String>: Surge 当前的 UI 语言。

持久存储

• $persistentStore.write(data<String>, [key<String>])

永久保存数据。 只允许使用字符串。 如果成功则返回真。

• $persistentStore.read([key<String>])

获取保存的数据。 返回一个字符串或 Null。

如果 key 未定义，则具有相同 script-path 的脚本共享存储池。 使用密钥时，可以在不同的脚本之间共享数据。

控制 Surge

• $httpAPI(method<String>, path<String>, callback<Function>(result<Object>))

您可以使用 $httpAPI 调用所有 HTTP API 来控制 Surge 的功能。 不需要身份验证参数。 有关可用功能，请参阅 HTTP API 部分。

实用工具

• console.log(message<String>)

  记录到 Surge 日志文件。

• setTimeout(function[, delay])

  与浏览器中的 setTimeout 相同。

• $httpClient.post(URL<String> or options<Object>, callback<Function>)

启动 HTTP POST 请求。 第一个参数可以是 URL 或对象。 一个示例对象可能看起来像这样。

{
  url: "http://www.example.com/",
    headers: {
    Content-Type: "application/json"
    },
  body: "{}"
}

使用对象作为选项列表时。 url 是必需的。 如果 headers 存在，它会覆盖所有现有的头字段。 body 可以是字符串或对象。 当呈现一个对象时，它被编码为 JSON 字符串，并且 Content-Type 设置为 application/json。

callback: callback(error, response, data)

成功时，错误为 Null，响应包含 status 和 headers。

类似功能：$httpClient.get, $httpClient.put，$httpClient.delete, $httpClient.head, $httpClient.options, $httpClient.patch。

• $notification.post(title<String>, subtitle<String>, body<String>)

发布通知。

• $utils.geoip(ip<String>)

执行 GeoIP 查找。 结果采用 ISO 3166 代码。

手动触发

您可以在 Surge iOS 上手动触发脚本，方法是长按脚本或使用系统 Shortcuts.app。

如果您使用 Shortcuts 触发脚本，您可以选择将参数传递给脚本，使用 $intent.parameter 来检索它。

（完）