sing-box 添加订阅配置教程：先确认格式，再完成导入与启动
简答：sing-box 添加订阅前，先确认订阅链接返回的是 sing-box JSON，而不是 Clash YAML、Base64 文本或单条节点链接。确认格式后，手机和桌面图形客户端使用 Remote 配置，Windows/Linux 命令行则保存为 JSON 文件并运行 sing-box check；通过校验、授权 VPN/TUN、选择节点后，才能确认配置真正生效。
定义：sing-box 订阅是一个由远程 URL 提供并可自动更新的 sing-box JSON 配置，图形客户端通常将其保存为 Remote Profile，命令行则需要下载或保存为本地配置文件。
先试这一步：确认订阅链接返回的是什么
本文是第三方使用指南，不是任何客户端或订阅服务的官方页面。sing-box 的配置文件格式是 JSON；官方文档列出的配置结构包括 dns、inbounds、outbounds 和 route 等字段，配置可使用 sing-box check 检查。可先查看官方配置文件说明。
| 返回内容 | 常见特征 | 处理方式 |
|---|---|---|
| sing-box JSON | 通常能看到 inbounds、outbounds、route 等 JSON 字段 | 可以尝试导入 Remote Profile 或保存为本地 JSON |
| Clash YAML | 常见顶层字段为 proxies、proxy-groups、rules | 不能直接当作 sing-box JSON；需要提供方提供 sing-box 格式或使用可信转换工具 |
| Base64 或编码文本 | 打开后不是 JSON，可能是一长串编码字符或多条节点链接 | 先确认提供方是否有 sing-box 专用订阅，不要直接改后缀 |
| 单条节点链接 | 只包含一个协议链接，不能形成完整配置 | 需要手动写入出站配置，或向提供方索取完整 sing-box 配置 |
在命令行中检查订阅返回内容时，使用 GET 请求并带上明确的 User-Agent。下面的命令会把响应头保存到 headers.txt，把正文保存到 subscription.json，不会在终端主动打印订阅内容：
curl -L -A "sing-box-guide/1.0" -D headers.txt -o subscription.json "订阅链接"
检查 headers.txt 中的 HTTP 状态码和 Content-Type，再打开本地文件确认是否为 JSON。PowerShell 中可执行：Invoke-WebRequest -Method Get -Uri "订阅链接" -Headers @{"User-Agent"="sing-box-guide/1.0"} -OutFile subscription.json。如果返回 401 或 403，优先检查订阅是否过期、访问权限是否变化；如果超时，先检查当前网络和域名解析。
Android：在 SFA 中添加 Remote 订阅
- 安装与设备兼容的 sing-box Android 客户端。官方将 Android 图形客户端称为 SFA，并说明它可以通过 Android
VpnService提供非特权 TUN；相关能力可查看官方 Android 功能说明。 - 打开 SFA 的配置或 Profiles 区域，选择新建远程配置，也就是 Remote Profile，粘贴订阅 URL，填写容易识别的名称并保存。Remote Profile 的定义是以 URL 作为更新来源的远程 sing-box 配置，官方通用客户端文档还说明其默认自动更新间隔为 60 分钟，可查看官方图形客户端通用说明。
- 手动执行一次更新，确认配置能够下载并被解析。若配置列表出现但节点或分组为空，不要先反复启动 VPN，先回到订阅返回内容检查：它可能是 Clash YAML、Base64、单条节点链接，或服务端返回了登录页。
- 在 Dashboard 或运行区域启动服务。Android 首次启动通常需要系统确认 VPN 连接；拒绝授权时，配置即使已经导入，也不会接管系统流量。
- 如果配置包含 Selector 或 URLTest 出站，启动后在 Groups 区域选择节点或测速组。官方通用客户端说明指出，图形客户端应在配置包含这类分组出站时提供分组选择功能。
iOS 与 macOS：Remote 配置和系统权限
Apple 平台客户端包括 SFI、SFM 和 SFT，官方说明它们都可以管理并运行本地或远程 sing-box 配置，并提供 TUN 透明代理实现；平台要求和下载渠道以官方 Apple 平台说明为准。
- 在 SFI 或 SFM 的 Profiles/配置区域新建 Remote Profile，输入订阅 URL 和配置名称，然后保存并手动更新。
- 确认配置状态正常后，再进入 Dashboard 或运行区域启动。首次启动时，按照系统弹窗允许 VPN 或网络扩展；如果只导入不启动，浏览器和其他应用不会自动使用该配置。
- 如果 macOS 上升级后看不到原有配置，先确认是否更换了应用。官方迁移文档说明，macOS 独立客户端在 1.14.0 迁移到新的应用标识后，旧应用的 Profiles 和设置不会自动继承；可查看官方迁移说明，不要直接删除旧数据。
- 如果配置可以更新但启动无网，先停止其他 VPN、代理或网络过滤软件，再重新启动网络扩展。若仍失败，打开客户端日志区域，重点看配置解析、DNS、TLS 和 TUN 启动错误，而不是只看节点名称。
Windows 与 Linux：下载配置、校验再运行
官方桌面客户端支持 Windows 10 及以上版本和 Linux 的 x64、arm64、armv7l 架构，并可管理本地或远程 sing-box 配置，具体平台范围见官方桌面客户端说明。如果使用桌面图形客户端，可按 Remote Profile 的方式添加；如果使用命令行核心，则按下面流程处理。
- 先用带 User-Agent 的 GET 请求下载配置，不要把订阅链接直接公开到截图、日志或公共仓库：
curl -L -A "sing-box-guide/1.0" --fail-with-body --silent --show-error "订阅链接" -o config.json。 - 进入保存配置的目录，执行检查命令：
sing-box check -c config.json。官方配置文档明确列出了sing-box check；如果提示 JSON 语法、未知字段或字段类型错误，应先修正格式或更新客户端，不要直接运行。 - 检查通过后运行：
sing-box run -c config.json。Linux 下若配置需要创建 TUN、修改路由或访问受保护资源，通常要使用具有相应权限的服务账户或sudo；Windows 下则按客户端提示授予管理员权限。 - 运行期间观察终端日志。命令行退出、端口占用、DNS 解析失败、证书错误和路由权限错误，通常都能在日志中区分。不要把包含订阅 URL、Cookie 或 token 的完整日志直接发到公开论坛。
自动更新、节点选择与生效验证
Remote Profile 适合订阅会变化的场景，本地 JSON 适合固定配置和命令行服务。官方通用客户端说明要求图形客户端实现远程配置自动更新，默认更新间隔为 60 分钟；如果服务端频繁变更节点，可保留默认值，不建议把更新间隔设置得过短，以免频繁请求导致服务端拒绝。
| 检查对象 | 正确现象 | 异常时先做什么 |
|---|---|---|
| 配置更新 | 更新时间变化，配置状态没有解析错误 | 检查 HTTP 状态码、订阅有效期和返回格式 |
| 分组 | Groups 中出现 Selector 或 URLTest 分组 | 检查配置是否真的包含对应出站，确认不是空订阅 |
| VPN/TUN | 系统显示 VPN 或网络扩展已连接 | 重新授权系统网络权限，停止其他冲突软件 |
| 实际流量 | 客户端 Dashboard 有连接或流量变化 | 检查是否选中节点，并查看 DNS、TLS 和路由日志 |
验证时不要只看“已启动”。先在客户端选择一个可用分组或节点，再访问一个普通网页，随后观察 Dashboard 的连接数和流量变化；如果只有服务状态、没有连接记录，说明配置可能已启动但应用流量尚未经过 sing-box。
常见报错的排查顺序
- 解析配置失败：先把响应保存为文件，确认它是 JSON；再执行
sing-box check -c config.json。若提示未知字段，核对客户端核心版本和配置字段变更，不要只改文件扩展名。 - 订阅更新 401/403：在
headers.txt查看 GET 返回状态，确认订阅权限、有效期和访问地址。不要在公开位置粘贴完整订阅链接。 - Groups 为空：检查配置是否包含 Selector 或 URLTest 出站。如果提供方只返回单个节点或其他客户端格式，sing-box 不会自动替它生成完整分组。
- 启动后无网络：先确认 VPN/TUN 权限，再看日志中的 DNS、路由和出站连接错误；同时停止其他 VPN、代理或网络过滤软件，避免多个虚拟网卡同时接管流量。
- 配置更新成功但节点不可用：更新成功只代表配置文件下载并解析成功，不代表每个节点都能连接。切换其他节点，分别观察 TLS、握手、超时和 DNS 错误。
最后核对：2026-10-25
添加 sing-box 订阅的最短路径是：确认返回内容为 sing-box JSON → 选择 Remote Profile 或保存为本地 JSON → 更新并检查配置 → 授权 VPN/TUN → 选择分组或节点 → 查看实际连接和日志。本文没有把 Clash、Base64 或单条节点链接直接认定为可导入格式，因为最终能否使用取决于订阅实际返回内容、客户端版本和配置字段。
如需用于跨平台办公和网络连接诊断的线路服务，可在完成客户端配置核验后了解边界云加速官网；本文与该服务的关系是独立的使用说明与服务入口。
常见问题
sing-box 订阅链接可以直接粘贴到客户端吗？
只有当链接返回的是 sing-box 可用的 JSON 配置时才适合直接添加为 Remote Profile。先用带 User-Agent 的 GET 请求保存响应，再确认内容不是 Clash YAML、Base64 或单条节点链接。
为什么 sing-box 显示订阅更新成功，但 Groups 里没有节点？
更新成功通常只代表远程内容已下载并解析，不代表内容包含 Selector、URLTest 或可用出站。请检查保存的 JSON 是否有 outbounds，以及配置是否真的包含分组出站。
Windows 或 Linux 添加订阅后如何确认配置有效？
将订阅保存为 config.json 后执行 sing-box check -c config.json；检查通过再执行 sing-box run -c config.json。运行时查看终端日志，重点关注 DNS、TLS、端口占用和 TUN 权限错误。
sing-box 启动后仍然无法上网怎么办？
先确认系统已经授权 VPN 或 TUN，再确认客户端已选择节点或分组。随后查看 Dashboard 是否产生连接记录，并在日志中区分 DNS、路由、握手和超时错误。