配置文件
Surgio 的配置文件位于目录内的 surgio.conf.js。
JavaScript 配置直接导出普通对象:
module.exports = {
artifacts: [],
urlBase: 'https://example.com/',
};
TypeScript Project 可以使用 satisfies SurgioProjectConfig 获得配置检查和 IDE 提示,同时保留对象自身的精确类型推断。
artifacts
- 类型:
Artifact[] - 默认值:
undefined - 必须
数组内容见 自定义 Artifact。
urlBase
- 类型:
string - 默认值:
/
规则文件的下载地址前缀。
以 / 结尾,如:https://example.com/ 。
remoteSnippets
- 类型:
RemoteSnippet[] - 默认值:
undefined
这个功能和 Surge 本身的 RULE-SET 功能无关,所以生成出来的规则可以在老版本的 Surge 和其它客户端中使用。
远程片段。你可以在这里配置符合 Surge Ruleset 标准 的文件,然后在模板中使用它们。
module.exports = {
remoteSnippets: [
{
url: 'https://github.com/Blankwonder/surge-list/raw/master/cn.list',
name: 'cn', // 模板中对应 remoteSnippets.cn
},
],
};
推荐的 RuleSet 列表:
从 v2.7.0 开始,你可以在这里配置符合 Surgio 片段 格式的文件。我们以 Surgio 推荐的 苹果服务规则 为例。
module.exports = {
remoteSnippets: [
{
url: 'https://raw.githubusercontent.com/geekdada/surge-list/master/surgio-snippet/apple.tpl',
name: 'apple', // 模板中对应 remoteSnippets.apple
surgioSnippet: true
},
],
};
使用:
{{ remoteSnippets.apple.main('🚀 Proxy', '🍎 Apple', '🍎 Apple CDN', 'DIRECT', '🚀 Proxy') }}
片段中宏的入参需要和 main 方法调用时的入参 一一对应,一个都不能少。
upload
- 类型:
object - 默认值:
undefined
上传到对象存储的配置。支持阿里云 OSS、Cloudflare R2 和其它 S3 兼容服务。
- 若删除了某个 Artifact,该规则文件会从对象存储中删除
- 每次上传都会覆盖原有的文件,所以请不要更改对象存储中的文件
- 上传命令会同步
prefix下的直接子对象,请不要在同一前缀中放置其它文件
访问凭证可以写入配置,也可以通过环境变量
S3_BACKEND_ACCESS_KEY_ID 和 S3_BACKEND_ACCESS_KEY_SECRET 提供。环境变量优先。
阿里云 OSS
省略 backend 时默认使用 OSS。推荐使用通用 Region ID,例如 cn-hangzhou、
ap-southeast-1 或 eu-central-1。旧格式 oss-cn-hangzhou 仍然可用。
module.exports = {
upload: {
backend: 'oss',
bucket: 'example-bucket',
region: 'cn-hangzhou',
endpointType: 'public',
prefix: '/',
},
};
endpointType 支持以下值:
public:公网 S3 兼容 Endpoint,默认值internal:同 Region 阿里云内网 Endpointaccelerate:传输加速 Endpoint,使用前需要为 Bucket 开启传输加速
也可以通过 endpoint 覆盖自动生成的地址。该字段只接受服务级 OSS Endpoint,
例如 https://oss-cn-hangzhou-internal.aliyuncs.com 或其
s3.oss-... 形式;已知的旧 Endpoint 会自动转换为 S3 兼容形式。
当前上传实现不支持绑定到单个 Bucket 的 CNAME Endpoint。若阿里云账号要求通过
CNAME 访问中国内地 Bucket,则不能使用 surgio upload。请勿将 CNAME 填入
upload.endpoint,配置校验会拒绝该地址。
Cloudflare R2
module.exports = {
upload: {
backend: 'r2',
bucket: 'example-bucket',
accountId: '0123456789abcdef0123456789abcdef',
prefix: '/',
},
};
欧盟或 FedRAMP Jurisdiction Bucket 需要额外设置 jurisdiction:
upload: {
backend: 'r2',
bucket: 'example-bucket',
accountId: '0123456789abcdef0123456789abcdef',
jurisdiction: 'eu', // 也可以是 'fedramp'
}
其它 S3 兼容服务
module.exports = {
upload: {
backend: 's3',
bucket: 'example-bucket',
endpoint: 'https://objects.example.com',
region: 'us-east-1',
pathStyle: true,
prefix: '/',
},
};
endpoint 必须是 HTTP 或 HTTPS URL,不能包含路径、认证信息、查询参数或锚点。
pathStyle 默认值为 true;若服务要求 Virtual-hosted-style 请求,请设置为
false。
upload.backend
- 类型:
'oss' | 'r2' | 's3' - 默认值:
oss
upload.prefix
- 类型:
string - 默认值:
/
默认保存至根目录,可以修改子目录名,以 / 结尾
upload.bucket
- 类型:
string - 默认值:
undefined - 必须
upload.region
- 类型:
string - OSS 默认值:
cn-hangzhou - S3 后端:必须
upload.endpoint
- 类型:
string - S3 后端:必须
upload.accountId
- 类型:
string - R2 后端:必须
Cloudflare Account ID,为 32 位十六进制字符串。
upload.jurisdiction
- 类型:
'eu' | 'fedramp' - 默认值:
undefined
仅用于 R2 Jurisdiction Bucket。
upload.pathStyle
- 类型:
boolean - S3 后端默认值:
true
仅用于通用 S3 后端。
upload.accessKeyId
- 类型:
string - 默认值:
undefined
推荐使用 S3_BACKEND_ACCESS_KEY_ID 环境变量,不要将该字段上传至公共仓库。
upload.accessKeySecret
- 类型:
string - 默认值:
undefined
推荐使用 S3_BACKEND_ACCESS_KEY_SECRET 环境变量,不要将该字段上传至公共仓库。
surgeConfig
- 类型:
object - 默认值:
undefined
// surgio.conf.js
module.exports = {
surgeConfig: {},
};
surgeConfig.vmessAEAD
- 类型:
boolean - 默认值:
true
默认开启 Vmess AEAD 加密,如果您的服务器不支持 AEAD 加密,请关闭。
surgeConfig.enableVless
- 类型:
boolean - 默认值:
false
开启后为 Surge 输出 Vless 节点,关闭时 Vless 节点会输出警告并被省略。VLESS Encryption 和 XHTTP 传输目前只有 Surge beta 版支持,请确认客户端版本后再开启。支持的参数组合见 Vless 节点。
也可以在单个节点上设置 surgeConfig: { enableVless: true },只为该节点开启。
quantumultXConfig
- 类型:
object - 默认值:
undefined
// surgio.conf.js
module.exports = {
quantumultXConfig: {},
};
quantumultXConfig.vmessAEAD
- 类型:
boolean - 默认值:
true
默认开启 Vmess AEAD 加密,如果您的服务器不支持 AEAD 加密,请关闭。
clashConfig
- 类型:
object - 默认值:
undefined
// surgio.conf.js
module.exports = {
clashConfig: {
clashCore: 'stash',
},
};
clashConfig.clashCore
- 类型:
string - 默认值:
clash.meta - 可选值:
clash,clash.meta,mihomo,stash
Clash 核心版本。默认使用 Mihomo(clash.meta)。mihomo 是 clash.meta 的别名,加载配置时会被归一化为 clash.meta。如果需要继续为旧版 Clash 生成配置,请显式设置为 clash。
下面是目前支持的变化:
| 核心 | 变化 |
|---|---|
clash | 使用旧版 Clash 的节点字段和规则过滤行为;省略 VLESS、TUIC、Hysteria2、AnyTLS、MASQUE、TrustTunnel、Tailscale 和使用 shadow-tls 的节点 |
clash.meta | 默认值;模板 clash 过滤器会改为过滤 Mihomo 不支持的规则 |
mihomo | clash.meta 的输入别名,加载后统一为 clash.meta |
stash | Hysteria 协议的密码字段改为 auth;模板 clash 过滤器会改为过滤 Stash 不支持的规则 |
clashCore 决定 Clash 订阅能否输出某类节点,Mihomo 和 Stash 会输出全部节点。v3 的 enableTuic、enableShadowTls、enableHysteria2、enableVless 已移除,配置中保留这些字段会导致校验失败。不想输出某类节点时,请使用过滤器。
clashConfig.enableSnellV6
- 类型:
boolean - 默认值:
false
开启后为 Mihomo 输出 Snell v6 节点,关闭时 Snell v6 节点会输出警告并被省略。Snell v6 需要包含 MetaCubeX/mihomo#3410 的 Mihomo 版本,请确认客户端版本后再开启。clashCore 为 clash 或 stash 时 Snell v6 节点始终会被省略。
也可以在单个节点上设置 clashConfig: { enableSnellV6: true },只为该节点开启。
surfboardConfig
- 类型:
object - 默认值:
undefined
// surgio.conf.js
module.exports = {
surfboardConfig: {},
};
surfboardConfig.vmessAEAD
- 类型:
boolean - 默认值:
true
默认开启 Vmess AEAD 加密,如果您的服务器不支持 AEAD 加密,请关闭。直接调用 getSurfboardNodes 时也使用此默认值。
surfboardConfig.geckoPassword
- 类型:
string,非空 - 默认值:未设置
仅用于 Surfboard 的 Hysteria2 Gecko 混淆,要求 Surfboard mobile 2.34.4+。可以在 Project 顶层设置,也可以在节点的 surfboardConfig 中覆盖。同一节点同时配置 Salamander 时,Gecko 优先。其他客户端输出不受此选项影响。
import { defineSurgioProject } from 'surgio/project'
export default defineSurgioProject({
surfboardConfig: { geckoPassword: 'shared-gecko-password' },
providers: {},
artifacts: [],
})
gateway
- 类型:
object - 默认值:
undefined
// surgio.conf.js
module.exports = {
gateway: {},
};
托管 API 相关配置
gateway.auth
- 类型:
boolean - 默认值:
false
是否开启鉴权,默认关闭。若开启则需要在访问 URL 上增加参数 access_token。
gateway.accessToken
- 类型:
string - 默认值:
undefined
用于调用接口和登录的鉴权码。
gateway.viewerToken
- 类型:
string - 默认值:
undefined
专门用于调用以下接口的鉴权码:
/get-artifact/export-providers/render
gateway.authProvider
- 类型:
(input: { request: Request }) => Promise<{ success: true; accessToken: string } | { success: false }> - 默认值:
undefined
用自己的代码判定请求者能否获得 viewer 身份,取代固定的 viewerToken。适用于订阅用户的 key 保存在外部后端的场景:每个用户使用自己的 key 访问,生成的订阅链接带的也是这个用户自己的 token。
// surgio.project.ts
export default defineSurgioProject({
gateway: {
auth: true,
accessToken: env('SURGIO_ACCESS_TOKEN'),
async authProvider({ request }) {
const bearer = request.headers
.get('authorization')
?.match(/^Bearer\s+(.+)$/i)?.[1]
const key =
bearer ?? new URL(request.url).searchParams.get('access_token')
if (!key) return { success: false }
const user = await lookupUser(key)
return user ? { success: true, accessToken: key } : { success: false }
},
},
})
async function lookupUser(key: string) {
const res = await fetch(
`https://backend.example.com/users/${encodeURIComponent(key)}`,
)
if (res.status === 404) return null
if (!res.ok) throw new Error(`用户后端返回 ${res.status}`)
return res.json()
}
request是标准 WebRequest。从哪里读取 key 由函数自己决定。accessToken是写进该用户生成链接中的 token,Gateway 会把它放在?access_token=参数里。面板和嵌入页又会把它当作 Bearer token 发回来。它与收到的 key 不同时,函数必须同时接受这个返回值。- 只有确认 key 无效时才返回
{ success: false },请求会得到 401,订阅客户端会把它当作 key 失效。 - 后端无法连接或超时时请抛出异常,请求会得到 5xx。
- 返回值与
gateway.accessToken相同时,Gateway 会返回 500。 - 只能给出 viewer 身份。admin 仍由
accessToken和面板登录决定,admin 请求不会调用该函数。
使用限制:
- 与
viewerToken二选一,同时配置会在加载配置时报错。 - 需要同时配置
gateway.auth: true和gateway.accessToken。 - 必须同时支持
?access_token=参数和Authorization: Bearer请求头两种携带方式。前者用于 Gateway 生成的链接,后者用于嵌入页/embed/artifact/:name。缺少任意一种,对应的入口会返回 401。 - 面板「分享」生成的嵌入页链接不带
access_token,避免把分享者的 token 交给他人。访问者需要在链接后加上自己的?access_token=,或由函数从请求的其他部分(例如 cookie)识别身份。 - Gateway 不缓存函数的结果。需要缓存时请在函数内部实现,这样后端吊销 key 后可以立即生效。
- 渲染缓存和
useCacheOnError的兜底缓存按用户分别保存,缓存条目数随用户数增长。使用 KV 或 Redis 时需要留意存储用量。 - 需要同时升级 surgio 核心和
@surgio/gateway,两者都支持 authProvider 才会生效。任意一边版本过旧,authProvider 会被忽略,所有订阅请求都得到 401。 - 函数会被原样带进 Worker 构建,其中引用的依赖必须能在 Worker 中运行。
surgio generate没有请求者,生成文件中的链接使用accessToken。
gateway.useCacheOnError
- 类型:
boolean - 默认值:
false
是否在 Artifact 生成错误时使用缓存(上一次正确请求的结果)。
如果 Artifact 中的某个 Provider 经常请求错误则建议开启这个选项,可以避免 Clash 等客户端在配置文件请求报错的时候崩溃。
- 应用重启后缓存会失效。
- 适用缓存的接口有
/get-artifact和/export-providers。 - 兜底副本与 Artifact 渲染缓存分开存放,缓存时长由
SURGIO_GATEWAY_ERROR_CACHE_MAXAGE控制,默认 1 天。
gateway.passRequestUserAgent
- 类型:
boolean - 默认值:
false
是否将 /get-artifact 请求中的 User-Agent 传递给上游机场的订阅服务器。这个选项主要用于解决某些机场的订阅服务器对 User-Agent 有特殊处理的问题。
开启后 Artifact 的渲染结果不再缓存。客户端 User-Agent 的取值没有上限,按 User-Agent 缓存会让缓存条目数随访问量无限增长。
gateway.passRequestHeaders
- 类型:
string[] - 默认值:
['x-surge-unlocked-features']
允许转发到上游订阅服务器的请求头白名单。配置后会从 /get-artifact 请求中选取对应的 Header 透传给订阅地址(Header 名称会统一转为小写)。
白名单之外的请求头不会离开 Gateway,也不会参与 Artifact 渲染缓存的 key。请只加入真正会改变上游返回结果的 Header:每多一个取值不固定的 Header(例如 Cookie、X-Forwarded-For),缓存条目数就会翻一倍。
// surgio.conf.js
module.exports = {
gateway: {
passRequestHeaders: ["x-custom"], // 不会覆盖内部默认值
},
};
passRequestUserAgent 为 true 时会自动包含 user-agent,无需重复配置。
customFilters
- 类型:
object - 默认值:
undefined
全局自定义 Filter。关于自定义 Filter 的用法,请阅读 进阶 - 自定义 Filter。
全局的过滤器优先级没有 Provider 中定义的过滤器高,如果遇到同名的过滤器则这里定义的值会被覆盖。
proxyTestUrl
- 类型:
string - 默认值:
http://cp.cloudflare.com/generate_204
模板中可以直接引用 {{ proxyTestUrl }} 来获取推荐的代理测试 URL。
proxyTestInterval
- 类型:
number - 默认值:
1200
模板中可以直接引用 {{ proxyTestInterval }} 来获取推荐的测试间隔。
internetTestUrl
- 类型:
string - 默认值:
http://connect.rom.miui.com/generate_204
模板中可以直接引用 {{ internetTestUrl }} 来获取推荐的联网测试 URL(检测设备是否联网而非梯子是否可用)。
internetTestInterval
- 类型:
number - 默认值:
1200
模板中可以直接引用 {{ internetTestInterval }} 来获取推荐的测试间隔。
customParams
- 类型:
object - 默认值:
{}
自定义的 全局 模板变量。可以在模板中获取,方便定制化模板。
- 全局模板变量的用法和 Artifact 中定义的模板变量相同,相关文档请查阅 这里;
- 在合并全局、局部模板变量和面板 URL 参数时的优先级为:URL 参数 > 局部 > 全局;
checkHostname
- 类型:
boolean - 默认值:
false
是否丢弃无法解析出域名 IP 地址的节点。无法解析出域名的节点有可能会导致 Clash 的 url-test 模式抛出异常而中止,丢弃这些节点可以避免这个问题。
某些机场的节点域名 TTL 非常小,在某些情况下可能会导致 DNS 回溯解析超时,这样会导致节点本身可用但是被抛弃,所以建议谨慎开启该选项。
resolveHostname
- 类型:
boolean - 默认值:
false
是否解析节点的域名。开启此功能后 Surgio 会将节点的域名解析为 IP 地址,这样可能可以加速节点的连接速度。
打开这个选项后,Surgio 会在生成配置的时候解析域名,这必然会造成生成时间延长,所以请按照个人的需要进行选择。另外,开启此选项后将失去节点的负载均衡功能(如有)和 DNS 解析的灵活性,所以请谨慎使用。
部分依赖 SNI 的节点假如你未手动设定 SNI,开启此功能后可能会导致节点无法连接。
flags
- 类型:
object - 默认值:
undefined
自定义国旗的添加规则。
Surgio 支持字符串和正则表达式的匹配方式,可以 emoji 和规则一对一,也可以一对多。这里的规则会合并到内置的规则中,同名(相同 emoji)的规则会被覆盖。
module.exports = {
// ...
flags: {
'🇪🇬': '埃及',
'🇮🇹': ['意大利', 'ITALY'],
'🇱🇰': ['斯里兰卡', /sri\slanka/i],
},
};
- 字符串的匹配方式是「包含」;
- 英文字母请使用大写;
cache
- 类型:
object - 默认值:
undefined
定义缓存的实现方式。默认情况下,Surgio 将缓存持久化到系统临时目录中的文件;常驻的 Node 服务可以使用 Redis,Serverless 环境可以使用 Upstash REST,Cloudflare Worker 可以注入 KV binding。所有实现共享同一套 TTL 行为,TTL 的单位为毫秒。
cache.type
- 类型:
string - 默认值:
filesystem - 可选值:
filesystem,redis,upstash,default
定义:
filesystem:使用本地文件存储,也是默认值redis:通过 TCP 连接 Redis,仅适用于 Nodeupstash:使用 Upstash Redis REST 接口default:filesystem的兼容别名
cache.directory
- 类型:
string - 默认值:系统临时目录中的 Surgio cache 目录
仅适用于 filesystem。可以用它指定缓存文件的存储目录:
module.exports = {
// ...
cache: {
type: 'filesystem',
directory: '/var/cache/surgio',
},
};
Redis
将 cache.type 设置为 redis 后,Surgio 优先读取配置中的 redisUrl,未配置时读取 REDIS_URL 环境变量。两者都缺失时,Surgio 在第一次访问缓存前报错。redisUrl 只接受 redis:// 或 rediss://(TLS)开头的地址。
module.exports = {
// ...
cache: {
type: 'redis',
redisUrl: process.env.MY_REDIS_URL,
},
};
Redis 只能在 Node 中使用,Cloudflare Worker 无法建立 Redis TCP 连接。更多说明参见 Redis 缓存。
Upstash REST
将 cache.type 设置为 upstash 后,Surgio 优先读取配置中的 upstashRestUrl 和 upstashRestToken,未配置的字段再从 UPSTASH_REDIS_REST_URL 和 UPSTASH_REDIS_REST_TOKEN 环境变量读取。
建议通过环境变量提供凭据:
module.exports = {
// ...
cache: {
type: 'upstash',
},
};
也可以显式配置 Upstash 实例:
module.exports = {
// ...
cache: {
type: 'upstash',
upstashRestUrl: 'https://example.upstash.io',
upstashRestToken: process.env.MY_UPSTASH_TOKEN,
},
};
Cloudflare KV binding
Cloudflare KV binding 是运行时对象,不写入 surgio.conf.js。在首次缓存访问前显式注入:
import { env } from 'cloudflare:workers';
import { cache } from 'surgio';
import { createCloudflareKvStore } from 'surgio/cache';
cache.useStore(createCloudflareKvStore(env.SURGIO_CACHE));
Cloudflare KV 是最终一致的存储:其他区域可能在最多约 60 秒内读到旧值,keys 和 reset 也受相同限制。Cloudflare 的物理过期最短为 60 秒;Surgio 会在缓存记录中保存精确的逻辑过期时间,因此不会返回逻辑上已经过期的值。
Cloudflare KV 适配器只代表 Surgio 的缓存模块可以使用 KV binding,并不表示 Surgio 的其它 Node.js 和文件系统功能可以直接运行在任意 Cloudflare Worker 环境中。
环境变量
Surgio 支持使用 环境变量 来调整没有公开的配置,但属于高级用法,请酌情使用。