跳到主要内容

v3 升级指南

在 v3.0.0 中对原有的一些接口和行为进行了修改，你可能要花一些时间来解决这些问题。相信我，会很快。

注意
  • 请不要在 package.json 中直接更改版本号
  • 请不要修改完直接提交代码
  • 请确认在本地运行 npx surgio generate 后没有报错再提交代码

Node 版本升级​

新版 Surgio 不再支持 Node v12，请使用 v18.0.0 以上版本。

如何升级 Surgio？​

npm i surgio@latest @surgio/gateway@latest --save

废弃功能​

请在你的仓库中搜索以下内容，然后根据提示进行修改。

  • 通过 External Provider 方式让 Surge 支持 Vmess 协议

    请使用 Surge 原生的 Vmess 支持

  • Surge 的 custom 节点格式

    移除 surgioConfig.surgeConfig.shadowsocksFormat

  • clashProxyConfig 和 proxyGroupModifier

    详情请阅读 https://url.royli.dev/YyKh1

  • surgioConfig.clashConfig.ssrFormat: "legacy"

    移除 surgioConfig.clashConfig.ssrFormat

  • patchYamlArray

    详情请阅读 https://url.royli.dev/xr9mj

  • 所有与 Quantumult 相关的功能

    请使用 Quantumult X

  • 所有与 Mellow 相关的功能

    请使用其它客户端

配置项变更​

所有的配置项都遵循一致的格式，不会再出现 kebabe-case 和 camelCase 混用的情况。

请在你的仓库中搜索并替换以下内容。

- udp-relay -> udpRelay
- obfs-host -> obfsHost
- obfs-uri -> obfsUri

新增功能​

Clash Meta 特性​

Tuic（v5 和旧版本）​

你可以通过开启 clashConfig.enableTuic 来为 Clash 订阅中的节点增加 Tuic 特性。

文档

Shadow TLS​

你可以通过开启 clashConfig.enableShadowTls 来为 Clash 订阅中的节点增加 ShadowTls 特性。

文档

Clash 特性​

支持 Wireguard 节点​

你不需要修改任何配置，Surgio 会自动为你生成 Wireguard 节点。

Surge 特性​

支持 Wireguard 节点​

Surge 的 Wireguard 节点配置包含两部分，[Proxy] 和与之对应的节点配置。你需要在模板中增加 getSurgeWireguardNodes 生成 Wireguard 节点。

[Proxy]
{{ getSurgeNodes(nodeList) }}

{{ getSurgeWireguardNodes(nodeList) }}

Tuic (v5)​

你不需要修改任何配置，Surgio 会自动为你生成 Tuic 节点。

针对客户端的节点名称生成方法​

原来 Surgio 仅提供 getNodeNames 来生成节点名称，现在你可以使用下面的方法来生成针对特定客户端的节点名称。他们会自动过滤掉不支持的节点类型。

  • getClashNodeNames
  • getQuantumultXNodeNames
  • getSurgeNodeNames
  • getSurfboardNodeNames
  • getLoonNodeNames

新的过滤器方法​

reverseFilter​

你可以使用 reverseFilter 来反转过滤器的结果。

const notUSFilter = reverseFilter(usFilter)

mergeReversedFilters​

你可以使用 mergeReversedFilters 来合并多个反转过滤器，discardKeywords, discardProviders, discardGlob 过滤器。

// 丢弃 US 和包含 BGP 关键字的节点
const notUSAndNotBGP = mergeReversedFilters(
  [notUSFilter, discardKeywords(['BGP'])],
  true, // 严格模式
)

// 香港 BGP ✅
// 香港 IPLC ✅
// 洛杉矶 BGP 🚫
// 洛杉矶 IPLC ✅

Provider 钩子函数​

afterNodeListResponse​

该钩子函数会在成功获取到远程订阅内容后执行。

文档

onError​

该钩子函数会在获取远程订阅内容失败后执行。

文档

自定义 Provider 增强​

nodeList 参数支持使用异步函数，这意味着你能够动态生成节点列表，更棒的是，你能获取到当前节点获取请求的 URL 参数。例如，你可以在请求中包含参数 hbo=1 时输出包含 HBO 节点的订阅。

文档

IDE 类型提示支持​

TypeScript Project 使用 satisfies SurgioProjectConfig 检查共享配置。Provider authoring helper 仍可按需使用，例如 defineClashProvider。

内置工具​

httpClient​

Surgio v3 的 httpClient 是一个 Got 实例。当前版本已改为基于 ky 的跨运行时封装；get 返回 { body, headers, statusCode }，Node.js 与 Cloudflare Worker 共用 Fetch、超时和重试逻辑。

cache​

Surgio v3 的 cache 是一个 cache-manager 实例，当时可以配置 Redis，否则使用内存缓存。当前版本已改用统一的 TtlCache，并移除了 Redis TCP 支持。

  • cache.get
  • cache.set
  • cache.del
  • cache.reset
  • cache.wrap
  • cache.keys
  • cache.mset
  • cache.mget
  • cache.mdel
  • cache.has