速云网络返回首页

sing-box客户端怎么配置订阅?远程配置、更新与连接排查

更新于 2026-11-14 · suyungo.buzz

简答:如果 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配置文件结构与检查命令。

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客户端说明。

  1. 打开sing-box for Android,进入配置列表或Profile管理区域,选择新增远程配置。不同构建版本的中文或英文菜单可能不同,核心对象应是Remote Profile,而不是新建空白Local Profile。
  2. 填写名称和订阅URL。名称只用于本机识别;URL应直接复制,避免漏掉问号、斜杠或授权参数。
  3. 保存后执行更新或刷新。更新成功不只看见配置名称,还应能打开配置内容或看到可用的出站、分组或相关状态。
  4. 选中该Profile并启动服务。系统首次运行可能要求授予VPN权限;如果配置使用TUN,需允许客户端建立系统VPN连接。
  5. 启动后先看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客户端说明

  1. 打开客户端的配置列表,选择新增远程配置或Remote Profile。
  2. 粘贴订阅URL并保存;如果客户端提供名称字段,填写便于区分的名称。
  3. 手动执行更新,确认配置内容已下载,而不是只显示一个空Profile。
  4. 选择该配置并启动服务,按系统提示允许VPN或网络扩展权限。
  5. 先检查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客户端说明

桌面平台导入入口与启动条件
平台配置入口导入方式启动前检查
macOSApple客户端的Profile列表新增Remote或Local Profile网络扩展、系统权限、TUN或系统代理状态
WindowsDesktop客户端的Profile列表新增Remote或Local ProfileTUN、系统代理、管理员权限和端口占用
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.json

curl --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导入。

  1. 首选:向配置提供方索取明确标注为sing-box格式的远程配置或JSON文件。
  2. 其次:如果只能取得其他格式,确认提供方是否给出转换方式,并要求转换后生成sing-box JSON。
  3. 转换后:把生成文件当作不可信输入,先检查JSON语法、outbounds、route和dns等部分,再导入客户端。
  4. 涉及隐私时:不要把含有个人订阅凭据的链接交给不明转换页面;在线转换可能记录URL、节点信息或配置内容。

如果没有可核实的转换工具或说明,最安全的操作建议是回到提供方索取兼容格式,而不是随意把完整订阅链接粘贴到第三方页面。

7. 导入失败、节点为空和启动后无网络:按阶段排查

提示格式错误或JSON错误

  • 先保存下载内容,确认它不是登录页、HTML错误页或截断文本。
  • 检查逗号、引号、括号和字段类型。
  • 使用命令行执行sing-box check -c config.json,把语法问题与网络问题分开。
  • 如果JSON合法但仍无法加载,再核对当前客户端支持的配置字段。

更新成功但没有节点或分组

  • 确认配置中是否存在outbounds。
  • 确认是否存在Selector或URLTest等可切换分组;没有分组时,Dashboard可能不会显示节点选择器。
  • 检查路由是否把流量指向direct、block或不可用的出口。
  • 如果配置来自转换流程,重新向提供方索取原生sing-box格式并对比。

启动成功但无法联网

  1. 关闭其他VPN、TUN或系统代理工具,避免多个程序同时接管流量。
  2. 确认系统VPN、网络扩展或TUN权限已允许。
  3. 分别测试域名和IP:只有域名失败时,优先检查DNS;两者都失败时,再看出站、路由、节点和当前网络。
  4. 查看客户端日志,确认请求是否进入预期出站,而不是被规则导向直连或阻断。
  5. 最后再比较不同网络环境;没有日志证据时,不要先批量修改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。文件名和路径需要替换为实际值。

订阅链接泄露后应该怎么处理?

把它当作访问凭据处理:停止传播,联系提供方撤销或重新生成链接,删除公开截图和日志,再用新链接重新导入。

相关阅读

参考资料

  1. sing-box图形客户端的Profile与Dashboard说明
  2. sing-box for Android客户端说明
  3. sing-box for Apple platforms客户端说明
  4. sing-box for Desktop客户端说明
  5. sing-box配置文件结构与检查命令
  6. curl命令手册:输出远程内容到本地文件
  7. Microsoft Learn:schtasks create命令说明