Basic Conversion

🔄 基本转换

主要转换接口：

GET /sub
HEAD /sub

最小请求需要 target 和 url。只有部署者已经启用插入节点时，url 才可以省略。

基本结构

https://后端地址/sub?target=目标格式&url=编码后的输入

示例：

https://api.asailor.org/sub?target=clash&url=https%3A%2F%2Fexample.com%2Fsub

URL 编码

url、config、rename 等值可能包含 ?、&、|、逗号或中文。构造完整请求时，需要对参数值进行 URL 编码。

错误示例：

url=https://example.com/sub?token=abc&mode=clash

这里的 &mode=clash 会被当作 /sub 自己的查询参数。

正确做法是把完整订阅 URL 编码后放入 url=。

合并多个输入

先使用 | 连接输入，再编码完整 url 值：

https://a.example/sub|https://b.example/sub|vless://节点链接

每一项可以是远程订阅或节点链接。最终处理方式取决于 target；详见远程订阅与客户端拉取。

常用参数

参数	作用	示例
target	选择目标格式	clash、surge、quanx
url	一个或多个订阅/节点输入	URL 编码后的字符串
config	选择远程或本地外部配置	URL 编码后的 HTTPS URL
include	仅保留名称匹配正则的节点	`香港
exclude	排除名称匹配正则的节点	`过期
rename	按规则重命名节点	需要 URL 编码
emoji	覆盖 Emoji 开关	true、false
list	生成节点列表；对 Clash 还会改变远程订阅路径	true
explain	返回诊断 JSON，不返回最终配置	true

完整列表见 API 参考。

筛选和远程资源

当目标使用客户端原生远程资源时，后端未必能提前读取远程订阅中的节点名称。能够表达筛选条件的客户端，会把 include / exclude 转换为远程资源过滤条件；不能等价表达时，诊断报告会显示相应路径或限制。

如果要求后端实际展开 Clash 订阅并筛选节点，可以显式使用 list=true，但这会重新引入后端访问订阅的网络和隐私边界。

常用节点选项

参数	作用
udp	覆盖目标能够表示的 UDP 选项
tfo	覆盖 TCP Fast Open 选项
scv	覆盖证书校验跳过选项
tls13	覆盖目标能够表示的 TLS 1.3 选项
append_type	在节点名称后追加类型
sort	启用节点排序
fdn	过滤已弃用节点

这些选项受目标格式能力限制。无法表示的组合可能被忽略、过滤或拒绝，不应假设所有客户端具有相同字段。

外部配置

&config=https%3A%2F%2Fexample.com%2Fconfig.ini

外部配置可定义基础模板、策略组、规则集、重命名和其他生成策略。显式外部配置加载失败时，不应把一个语义不同的默认配置当作成功结果；具体回退行为由部署配置决定。

详见外部配置与模板。

响应检查

成功响应至少需要检查：

• HTTP 状态为 200；
• Content-Type 与目标内容相符；
• 响应不是 HTML 错误页；
• 配置中存在有效节点或远程资源；
• 客户端能够加载配置。

响应可能包含 Subscription-UserInfo、profile-update-interval、Content-Disposition 等目标相关头。不要把响应头当作唯一成功标准。

HEAD 请求

HEAD /sub 执行与 GET 相同的参数和转换检查，但不返回响应正文。它适合确认请求是否可生成，不适合验证最终配置内容。

下一步

• 调整 Provider：特色参数与扩展语法
• 理解不同客户端更新订阅的方式：远程订阅与客户端拉取
• 请求失败：请求诊断