sing-box客户端怎么配置订阅?远程配置、更新与连接排查
简答:如果 sing-box 粘贴订阅后显示失败、配置为空或启动后无法联网,先检查返回格式,再按设备添加 Remote Profile,更新后确认配置、权限和出站是否生效。Android、Apple、Windows 与 Linux 的入口名称可能不同,但排查顺序基本一致:下载、解析、启动、连接。
定义:sing-box订阅配置,是把远程URL或本地JSON配置交给sing-box客户端管理,并在更新后运行其中的DNS、入站、出站和路由设置。
1. 30秒速查卡:先看订阅返回内容,再决定怎么导入
如果你已经有订阅链接,先不要直接反复点击更新。sing-box配置文件使用JSON,官方示例包含dns、inbounds、outbounds和route等顶层字段;但浏览器能打开链接,只能说明服务器返回了内容,不能单独证明内容就是可运行配置。可先查看sing-box配置文件结构与检查命令。
| 返回内容 | 优先判断 | 下一步 | 失败时先查 |
|---|---|---|---|
| 完整JSON对象 | 可能是远程sing-box配置 | 添加为Remote Profile并更新 | JSON语法、字段结构和客户端支持范围 |
| 登录页、403、404、429或错误文本 | 不是可用配置 | 确认链接权限、有效期和访问条件 | 订阅地址与下载链路 |
| Clash YAML | 不能直接认定为sing-box配置 | 优先向提供方索取sing-box格式 | 格式是否与客户端匹配 |
| Base64或单节点文本 | 通常不是完整JSON配置 | 按提供方支持方式转换或手动配置 | 是否缺少DNS、路由、入站或出站 |
| 本地JSON文件 | 可作为Local Profile | 导入后先执行配置检查 | 文件路径、权限和字段版本 |
最快判断:如果返回的是网页、错误信息、空内容或无法解析的文本,先修复链接;如果是JSON,再检查结构;只有下载、解析都通过后,才进入启动和节点选择阶段。不要把包含访问凭据的完整订阅URL发到公开论坛、群聊或截图中。
2. Android端:新增Remote Profile,更新后再启动
官方客户端列表将Android客户端列为 sing-box for Android;其客户端页面说明可以管理和运行本地或远程sing-box配置,并提供基于系统VPN能力的TUN功能。可参考sing-box for Android客户端说明。
- 打开sing-box for Android,进入配置列表或Profile管理区域,选择新增远程配置。不同构建版本的中文或英文菜单可能不同,核心对象应是Remote Profile,而不是新建空白Local Profile。
- 填写名称和订阅URL。名称只用于本机识别;URL应直接复制,避免漏掉问号、斜杠或授权参数。
- 保存后执行更新或刷新。更新成功不只看见配置名称,还应能打开配置内容或看到可用的出站、分组或相关状态。
- 选中该Profile并启动服务。系统首次运行可能要求授予VPN权限;如果配置使用TUN,需允许客户端建立系统VPN连接。
- 启动后先看Dashboard或状态页,再测试普通网页。若只有部分应用可用,检查路由、DNS和应用分流,不要先反复刷新订阅。
官方通用客户端说明把Remote Profile定义为以URL作为更新来源的远程配置,并说明图形客户端应提供配置查看和自动更新能力;因此,Android端的正确思路是“远程配置更新成功后再启动”,而不是把订阅链接当作单个节点直接粘贴。sing-box图形客户端的Profile与Dashboard说明
3. iPhone和iPad:使用Apple客户端的远程配置能力
iPhone和iPad使用sing-box for Apple platforms。官方页面说明该客户端可以管理和运行本地或远程sing-box配置,并提供包括TUN透明代理在内的平台功能。sing-box for Apple platforms客户端说明
- 打开客户端的配置列表,选择新增远程配置或Remote Profile。
- 粘贴订阅URL并保存;如果客户端提供名称字段,填写便于区分的名称。
- 手动执行更新,确认配置内容已下载,而不是只显示一个空Profile。
- 选择该配置并启动服务,按系统提示允许VPN或网络扩展权限。
- 先检查Dashboard中的运行状态、连接数量或分组,再测试域名和普通网页。
如果更新失败,先在浏览器中检查链接是否返回登录页或错误页;如果更新成功但启动失败,再看JSON结构、系统权限和配置中的DNS、路由及出站。iPhone、iPad的具体按钮文字以当前客户端显示为准,本文不把未在官方页面明确列出的菜单名称当作固定入口。
4. macOS、Windows与Linux:图形客户端或命令行按类型处理
官方图形客户端列表目前将iOS、macOS和Apple tvOS归为Apple平台,将Windows和Linux归为Desktop客户端。Windows与Linux的官方Desktop页面说明,该客户端可以管理和运行本地或远程sing-box配置,并提供包括TUN透明代理在内的平台功能。sing-box for Desktop客户端说明
| 平台 | 配置入口 | 导入方式 | 启动前检查 |
|---|---|---|---|
| macOS | Apple客户端的Profile列表 | 新增Remote或Local Profile | 网络扩展、系统权限、TUN或系统代理状态 |
| Windows | Desktop客户端的Profile列表 | 新增Remote或Local Profile | TUN、系统代理、管理员权限和端口占用 |
| Linux图形客户端 | Desktop客户端的Profile列表 | 新增Remote或Local Profile | 运行权限、TUN权限、DNS和路由 |
| Linux、Windows或macOS命令行 | 本地JSON文件 | 下载后使用sing-box check和sing-box run | 文件路径、配置结构和进程日志 |
图形客户端的通用逻辑是:新增Profile、填写远程地址、更新、选择配置、启动服务、查看Dashboard。官方说明还提到,当配置包含Selector或URLTest等分组出站时,Dashboard可以提供分组选择;如果配置本身没有这些出站,客户端就不一定会出现可切换的节点组。sing-box Profile和Dashboard功能说明
命令行用户可以先把远程配置保存为本地文件,再检查并运行。下面的URL和文件名都是示例值,请替换成自己的地址;不要把真实订阅URL写进公开脚本:
curl --fail --location --output config.json "https://example.com/your-sing-box-config.json"
sing-box check -c config.json
sing-box run -c config.jsoncurl --output用于把远程响应写入指定文件;相关参数说明可查看curl命令手册。sing-box官方配置文档列出了check、format和merge等命令;检查不通过时,先修JSON和字段,不要直接启动。
5. 命令行远程更新:先下载临时文件,再替换已验证配置
远程配置自动更新有一个实际风险:如果下载到的是登录页、错误页或损坏JSON,直接覆盖正在使用的配置可能导致服务无法启动。更稳妥的流程是下载到临时文件、检查通过后再替换正式文件。
macOS与Linux:curl加本地脚本
#!/bin/sh
set -eu
URL="https://example.com/your-sing-box-config.json"
TARGET="$HOME/sing-box/config.json"
TMP="$TARGET.tmp"
curl --fail --location --output "$TMP" "$URL"
sing-box check -c "$TMP"
mv "$TMP" "$TARGET"该脚本只负责下载和检查,不负责重启进程。你可以先手动运行并查看结果,再根据自己的进程管理方式安排定时任务。定时更新的间隔、重启方式和权限应按运行环境单独配置,不能假定所有Linux发行版或macOS安装方式都相同。
Windows:PowerShell下载后检查
$url = "https://example.com/your-sing-box-config.json"
$target = "$env:USERPROFILE\sing-box\config.json"
$tmp = "$target.tmp"
Invoke-WebRequest -Uri $url -OutFile $tmp
sing-box check -c $tmp
Move-Item -Force $tmp $target如果要使用Windows任务计划程序,可以用schtasks注册定时任务,但任务运行账户、文件路径和权限必须先核对。微软文档说明了schtasks /create的计划类型、任务名和执行命令参数,具体可查看schtasks create命令说明。先手动执行脚本,再安排自动更新,能更容易区分下载失败、JSON失败和权限失败。
6. Clash、Surge或Base64订阅不能直接假定兼容
sing-box官方配置文件使用JSON结构,因此不能只看“订阅链接”四个字就判断格式兼容。Clash常见配置可能是YAML,Base64订阅通常是编码后的节点文本,Surge配置也可能包含不同的字段和规则表达方式;这些内容都不应直接当作sing-box JSON导入。
- 首选:向配置提供方索取明确标注为sing-box格式的远程配置或JSON文件。
- 其次:如果只能取得其他格式,确认提供方是否给出转换方式,并要求转换后生成sing-box JSON。
- 转换后:把生成文件当作不可信输入,先检查JSON语法、
outbounds、route和dns等部分,再导入客户端。 - 涉及隐私时:不要把含有个人订阅凭据的链接交给不明转换页面;在线转换可能记录URL、节点信息或配置内容。
如果没有可核实的转换工具或说明,最安全的操作建议是回到提供方索取兼容格式,而不是随意把完整订阅链接粘贴到第三方页面。
7. 导入失败、节点为空和启动后无网络:按阶段排查
提示格式错误或JSON错误
- 先保存下载内容,确认它不是登录页、HTML错误页或截断文本。
- 检查逗号、引号、括号和字段类型。
- 使用命令行执行
sing-box check -c config.json,把语法问题与网络问题分开。 - 如果JSON合法但仍无法加载,再核对当前客户端支持的配置字段。
更新成功但没有节点或分组
- 确认配置中是否存在
outbounds。 - 确认是否存在Selector或URLTest等可切换分组;没有分组时,Dashboard可能不会显示节点选择器。
- 检查路由是否把流量指向
direct、block或不可用的出口。 - 如果配置来自转换流程,重新向提供方索取原生sing-box格式并对比。
启动成功但无法联网
- 关闭其他VPN、TUN或系统代理工具,避免多个程序同时接管流量。
- 确认系统VPN、网络扩展或TUN权限已允许。
- 分别测试域名和IP:只有域名失败时,优先检查DNS;两者都失败时,再看出站、路由、节点和当前网络。
- 查看客户端日志,确认请求是否进入预期出站,而不是被规则导向直连或阻断。
- 最后再比较不同网络环境;没有日志证据时,不要先批量修改DNS或MTU。
如果订阅URL已经泄露,应停止继续传播,联系提供方撤销或重新生成链接,并删除公开截图、日志和脚本中的旧URL。本文不对任何具体订阅的有效期、节点数量、连接速度或可用性作保证。
常见问题
sing-box可以直接导入Clash订阅吗?
不能仅凭链接名称判断。sing-box配置使用JSON,Clash订阅可能是YAML或其他格式。优先向提供方索取明确的sing-box配置;如果必须转换,转换后先检查JSON、出站、路由和DNS。
订阅链接能在浏览器打开,为什么sing-box仍然导入失败?
浏览器能打开只说明服务器返回了内容,返回内容可能是登录页、错误页、文本或不符合sing-box结构的JSON。应先保存响应并检查格式,再排查客户端权限和网络。
Android导入后一定要开启TUN吗?
不一定。是否使用TUN取决于配置和希望接管的流量范围;需要通过Android系统VPN能力接管流量时,必须允许VPN权限,同时避免与其他VPN工具并行运行。
更新后没有节点或分组怎么办?
先确认配置中存在outbounds,再检查是否包含Selector或URLTest等分组出站;随后查看路由和客户端日志。不要在未确认下载内容正常前反复更换客户端。
没有sing-box格式,只有Base64订阅怎么办?
首选向提供方索取sing-box远程配置或JSON文件。若对方提供转换方式,转换后先在本地检查,不要把含访问凭据的完整链接交给不明在线转换页面。
命令行如何检查配置是否能运行?
把配置保存为本地JSON后执行sing-box check -c config.json;检查通过后再执行sing-box run -c config.json。文件名和路径需要替换为实际值。
订阅链接泄露后应该怎么处理?
把它当作访问凭据处理:停止传播,联系提供方撤销或重新生成链接,删除公开截图和日志,再用新链接重新导入。