订阅转换参数怎么填写:核心字段、格式选择与排错步骤
简答:订阅转换最小填写方式是:先把完整订阅地址进行 URL 编码,再填写 target=目标格式,通常先留空 config、include、exclude 等高级参数。生成后返回的内容应是目标客户端配置,而不是 HTML 错误页或空文件;如果没有节点,优先检查原订阅、编码和目标格式。
定义:订阅转换参数,是通过 URL 查询参数告诉转换后端“读取哪份订阅、输出什么客户端格式,以及是否套用规则、筛选节点或设置更新属性”的字段集合。
先照这个最小模板填写:入口、动作、成功信号
如果你只是想把已有订阅转换成客户端能导入的配置,先不要填写所有高级选项。以自建或可信转换后端为例,基础请求通常类似 https://转换服务地址/sub?target=clash&url=已编码的订阅地址。官方 subconverter 文档把 target 定义为输出类型,把 url 定义为待转换的订阅或节点链接,并说明参数值需要先进行 URL 编码;入口格式可参考 subconverter 官方 README。
- 入口:打开转换页面,或使用服务方提供的转换接口;确认地址确实是转换接口,不要把订阅地址本身误填成后端地址。
- 动作:把原始订阅填入
url,选择与客户端对应的target,第一次生成时让config、include、exclude、rename保持空白。 - 预期结果:返回 YAML、JSON、conf 或节点链接等目标格式内容,且能被对应客户端识别。
- 失败分支:如果返回 HTML、404、403、超时或空内容,先在浏览器或命令行单独检查原订阅,再检查后端地址、编码和目标格式。
- 最短回退:删除全部高级参数,只保留
target与url重新生成;确认成功后再一次增加一个参数。
注意:订阅链接通常包含账号凭据或可代表账户的访问信息。不要把真实链接放进公开 issue、截图、聊天记录或日志;排错时使用已脱敏的占位地址。
核心参数对照:哪些必填,哪些可以留空
不同前端或后端可能增加自定义字段,下面以官方 subconverter 文档中公开的常见参数为基础。实际页面若字段名称不同,应以当前页面的字段说明为准。
| 参数 | 是否通常必填 | 填写内容 | 新手建议 |
|---|---|---|---|
url | 是 | 完整订阅地址、单条节点链接,或多个输入合并后的值 | 先确认原链接单独访问能返回订阅内容,再编码 |
target | 是 | 目标客户端或配置格式,例如 clash、quanx、loon、surge、v2ray | 按客户端选,不要只看名称相似 |
config | 否 | 远程或本地外部配置文件,通常包含规则、策略组或模板设置 | 首次转换留空,确认基础配置可用后再加 |
include | 否 | 只保留名称匹配的节点,通常支持正则表达式 | 先用一个普通关键词测试,避免正则写错导致零节点 |
exclude | 否 | 排除名称匹配的节点,通常支持正则表达式 | 不要与 include 同时复杂叠加 |
filename | 否 | 生成文件的显示名称 | 只影响名称,不会修复格式或连接问题 |
interval | 否 | 托管配置或远程订阅的更新间隔,常以秒表示 | 只有后端和客户端都支持时才设置 |
rename | 否 | 节点名称重命名规则 | 最后再加,避免把名称改乱后无法筛选 |
官方中文文档还列出了 group、dev_id、upload_path、filter_script 等进阶字段,但它们依赖特定客户端、部署方式或服务端能力,不应当当作通用必填项。字段定义可查看 subconverter 中文参数说明。
target 怎么选:按客户端格式,而不是按节点协议
target 决定输出文件的结构,和原订阅里的节点协议不是一回事。比如原订阅可能同时包含多种节点,但目标客户端只能识别其中一部分;转换成功不代表所有节点或所有规则都能被目标格式完整表达。
| 使用场景 | 优先尝试的 target | 核对重点 |
|---|---|---|
| Mihomo 或兼容 YAML 的客户端 | clash | 确认客户端接受对应 YAML 结构,以及规则、代理组字段是否兼容 |
| sing-box 配置 | singbox 或后端明确支持的同名值 | 以当前转换项目的支持列表为准,不能把 Clash YAML 当作 sing-box JSON |
| Surge | surge | 部分版本可能需要额外版本参数;规则和节点类型可能被转换或跳过 |
| Quantumult X | quanx | 确认输出是资源配置还是节点列表,并检查规则格式 |
| Loon、Surfboard 等 | loon、surfboard | 以转换后端支持列表和客户端导入方式为准 |
| 只需要分享链接或节点列表 | v2ray、ss、ssr 等 | 确认客户端要的是 Base64 节点列表、单条链接还是完整配置文件 |
官方仓库列出了 Clash、Quantumult、Quantumult X、Loon、Surge、V2Ray、SSR 等输入或输出类型;其后续版本说明也记录了 sing-box 配置生成能力。由于不同转换实现的支持范围可能不同,sing-box 等格式应以当前后端的支持表为准,不能仅凭搜索结果中的参数名推断。可参阅 官方 release 说明。
url 参数怎么填:完整订阅、单节点和多个订阅
1. 完整订阅地址
完整订阅地址通常是订阅提供方生成的一条 HTTPS 地址,可能带有路径、问号和一长串参数。它和单条 ss://、vmess://、vless:// 等节点链接不同:前者通常用于批量获取节点,后者只代表一个节点或一项分享信息。
2. 为什么要 URL 编码
当原链接含有 ?、&、#、中文或多个订阅分隔符时,直接拼入转换接口可能被误解析。应先对整个参数值进行百分号编码,再放到 url= 后面。百分号编码属于 URI 的通用语法机制,可参考 RFC 3986 URI Generic Syntax。
不要只编码域名,也不要把已经编码过的字符串重复编码。稳妥做法是:复制原始链接到本地编码工具或脚本中,编码一次,然后检查 ?、&、# 是否已转为类似 %3F、%26、%23 的形式。
3. 多个订阅如何合并
官方 subconverter 示例采用竖线 | 连接多个输入,然后对包含竖线的完整字符串整体编码。例如,先得到 订阅A|订阅B,再把整个值编码成 订阅A编码值%7C订阅B编码值。不要先分别生成两个转换链接再把两个生成链接拼接;那样通常不是同一份配置。
4. 单条节点链接的限制
单条节点可以作为输入的前提是后端支持该协议和该输入形式。若输入能生成文件但结果只有一个节点,这是正常现象;若提示格式错误,应先确认链接没有被聊天软件截断、换行或自动转义。
config、include、exclude 与远程规则怎么逐步加入
config 通常代表外部配置文件,不等同于转换后端地址,也不等同于最终导入客户端的订阅地址。它可能包含规则集、代理组、模板或其他生成参数;官方文档明确说明外部配置通过 &config= 传入,并且其中的设置可能覆盖主程序配置。
- 先不填 config:验证原订阅和目标格式能正常生成。
- 再填 config:确保该文件是当前后端能读取的格式,并对配置地址本身进行 URL 编码。
- 检查返回内容:如果加入后突然变成空文件、HTML 或规则错误,先移除 config,确认问题确实来自外部配置。
include 和 exclude 通常按节点备注筛选。假如节点名称包含“东京”,可以先用简单关键词测试;如果后端要求正则表达式,再使用括号、竖线等表达式。筛选顺序建议是先 include,再根据结果增加 exclude;一开始同时写复杂正则,很难判断是没有匹配,还是后端没有读取参数。
一个安全的验证顺序是:基础转换 → 只加 include → 检查节点数量 → 再加 exclude → 最后处理 rename。节点数量减少并不一定代表原订阅失效,也可能是筛选条件、目标格式兼容性或转换器跳过了无法表达的协议。
生成后怎么导入:成功信号、自动更新与回退
- 预览:先检查响应类型。Clash/Mihomo 类输出通常应是 YAML,sing-box 通常应是 JSON,Surge 类输出通常是文本配置;不要把错误页保存成配置文件。
- 导入:在客户端选择“从 URL 添加远程配置”“订阅链接”或同义入口,粘贴生成后的转换地址,而不是再次粘贴原始订阅地址。
- 验证:客户端能读取配置、显示节点或代理组,并且刷新时仍能重新取得内容,才算导入成功。
- 更新:如果使用的是远程转换地址,客户端刷新时可能再次请求转换后端;是否支持更新间隔、缓存或远程配置,要看当前客户端和后端实现。
- 回退:保留原始订阅地址和上一次可用的转换地址。新配置失败时,先切回旧配置,再删除新增的高级参数。
如果使用自建转换服务,官方 Docker 文档给出的基本验证方式是启动后访问本地版本接口,确认后端已经运行;这只能证明服务进程响应,不能证明原订阅、规则或目标格式一定可用。相关部署说明见 subconverter 官方 Docker 文档。
常见失败排查:按原因而不是按报错猜
| 现象 | 优先检查 | 处理方式 |
|---|---|---|
| 返回 404、403 或超时 | 后端地址、接口路径、网络连通性 | 确认转换服务根地址与 /sub 路径是否匹配;不要自行添加未核实的路径 |
| 返回 HTML 而不是配置 | 接口地址、反向代理、错误页 | 用浏览器开发者工具或命令行查看状态码和响应头,回到最小模板测试 |
| 转换后没有节点 | 原订阅、URL 编码、include/exclude | 直接验证原订阅;移除筛选参数;确认目标格式支持输入协议 |
| 节点数量变少 | 筛选条件或目标格式兼容性 | 先取消 include、exclude 和 rename,再逐个恢复;不要把数量变化直接判定为线路故障 |
| 规则没有生效 | config 是否被读取、规则格式是否被目标客户端支持 | 先使用默认配置验证节点,再检查外部配置和客户端日志 |
| 客户端无法更新 | 转换地址是否仍可访问、客户端是否保留远程配置 | 重新复制生成地址;若服务要求登录、令牌或固定路径,以服务说明为准 |
排错时每次只改一个变量,并记录原始值。尤其不要为了“修复”而反复公开真实订阅链接;如果链接已经出现在公开位置,应按照订阅提供方支持的方式处理凭据更换或失效。
在线转换还是本地转换:怎么选更稳妥
在线转换的优点是无需安装,适合临时验证格式;代价是转换请求可能经过远程服务,具体是否下载、缓存或记录订阅内容取决于服务端实现,不能仅凭页面外观判断。自建或本地转换可以减少对公共后端的依赖,但需要自行维护程序、配置、规则和访问控制。
| 选择 | 适合人群 | 主要注意事项 |
|---|---|---|
| 在线转换 | 只想快速测试目标格式 | 不要提交不必要的真实凭据;先查看服务说明和隐私政策 |
| 本地运行 | 需要长期使用或处理敏感订阅 | 保存配置文件权限,限制监听地址,升级前备份 |
| 自建后端 | 需要多人或多设备使用 | 配置 HTTPS、访问控制和日志脱敏;不要把接口直接暴露给公网 |
官方项目的 Docker 示例展示了本地端口映射和版本接口检查,但部署安全、反向代理、访问控制仍需自行配置。任何“转换成功”都只说明某次请求返回了结果,不等于节点延迟、丢包、跨境办公可用性或长期连接质量得到保证。
常见问题
订阅转换参数里 url 和后端地址有什么区别?
后端地址是提供转换接口的服务入口,通常还要配合接口路径;url 是交给后端读取的原始订阅或节点输入。两者不能互相替代,具体路径必须以当前转换服务的公开说明为准。
url 参数已经带问号和参数,还需要编码吗?
需要把作为 url 参数值的整个原始地址进行一次 URL 编码,尤其注意问号、&、井号和中文。不要只编码域名,也不要对已经编码的结果重复编码。
config 参数必须填写吗?
通常不必。基础转换只需要 url 和 target;config 多用于外部规则、策略组或模板。新手应先留空,确认基础结果能导入后再加入。
为什么 target 选错后会有节点但客户端仍无法导入?
节点能被解析不代表输出结构符合客户端要求。target 决定生成的配置格式,必须与客户端匹配;例如 YAML、JSON、Surge 文本配置和节点列表不是同一种文件。
include 和 exclude 同时填写后没有节点怎么办?
先删除 exclude,只保留 include 测试;如果仍为空,再删除 include,验证基础订阅。复杂正则、大小写、节点备注变化或目标格式过滤都可能造成结果为空。
转换后节点变少,是原订阅失效了吗?
不一定。可能是筛选参数生效,也可能是目标格式无法表达某些协议或字段。先取消 include、exclude 和自定义 config,再比较基础转换结果;不要用节点数量直接判断网络质量。