sing-box 订阅导入与配置教程:从链接到启动代理
简答:先确认订阅提供方给的是 sing-box 远程配置或 JSON,而不是只适用于其他客户端的链接;随后在对应客户端添加 Remote 配置,刷新并启用,最后分别验证配置解析、VPN或TUN权限、节点连通性和DNS。
定义:sing-box 订阅导入,是把订阅提供方生成的远程配置URL或本地JSON配置加入sing-box客户端,并通过更新、选择出站组和启动服务完成使用。
先试这一步:判断订阅格式,再决定导入方式
本文是第三方使用指南,非 sing-box 官方页面。sing-box 的配置文件格式是 JSON;官方图形客户端把配置区分为 Local、iCloud 和 Remote,其中 Remote Profile 以 URL 作为更新来源,并支持自动更新。官方配置说明与官方图形客户端通用说明都没有把其他客户端的订阅格式默认视为 sing-box 配置,因此不要看到“订阅链接”四个字就直接导入。
| 你手里的内容 | 常见特征 | 正确处理方式 |
|---|---|---|
| sing-box 远程配置 | 提供方明确写明 sing-box、JSON 或 Remote | 在客户端新建 Remote Profile,粘贴 URL,保存后刷新 |
| 本地 JSON 文件 | 文件内容以大括号开始,包含 log、dns、inbounds、outbounds 或 route 等字段 | 选择 Local Profile 或导入本地配置,再执行配置检查 |
| 其他客户端配置 | 可能是 YAML、特定客户端链接或只含节点分享内容 | 先向订阅提供方确认是否提供 sing-box 格式,不要默认兼容 |
| 单个节点分享链接 | 只描述一个节点,不包含完整路由、DNS 或出站组 | 不能当作完整订阅;需要手动转换为合法 JSON 或索取完整配置 |
最快判断标准:如果提供方没有明确写“sing-box”“JSON”或“Remote”,先不要反复点击导入;复制链接到浏览器或使用文本查看方式检查返回内容是否为 JSON。订阅链接通常包含访问凭据,不要粘贴到公开论坛、截图或不明第三方转换站。
Android 和 iOS:添加 Remote 配置并启动
- 准备订阅链接。从订阅提供方的配置面板复制 sing-box 兼容链接。不要把登录页地址、节点单独分享链接或其他客户端专用地址当成 Remote URL。
- 进入配置文件区域。在 Android 客户端或 Apple 平台客户端中打开 Profiles、配置文件或同义入口,选择新增 Remote Profile。官方通用规范将 Remote Profile 定义为“以 URL 为更新来源的远程 sing-box 配置”。查看 Remote Profile 说明
- 填写 URL 并保存。名称可以写成“工作线路”或“个人配置”,URL 粘贴完整订阅地址;如果提供方另行给出 HTTP Basic 用户名和密码,按其说明填写,不要把密码写进公开配置。
- 手动更新一次。保存后点击 Update、刷新或同义按钮。更新成功后再启用配置;不要在尚未完成下载时直接判断节点不可用。官方通用说明提到 Remote Profile 应支持自动更新,默认更新间隔为 60 分钟,但具体按钮名称会随平台和版本变化。查看官方通用行为
- 启动服务并授权。Android 通常需要允许 VPN 服务;Apple 平台使用 NetworkExtension 提供未授权 TUN 实现,首次启动时应按系统提示允许添加 VPN 配置。Android 官方客户端特性 Apple 平台官方客户端特性
- 选择节点或出站组。如果配置含 Selector 或 URLTest 等出站组,Dashboard 或状态页通常会显示分组选择入口;如果只有单个出站,就不会出现节点列表。官方文档明确将 Groups 与 Selector、URLTest 关联。官方 Groups 说明
- 验证是否真正生效。先看客户端状态是否为运行,再打开一个普通网页或应用;随后检查连接记录、流量统计和 DNS 是否有请求。只看到“已启动”不等于节点可用,应继续查看日志和连接状态。
如果 Android 启动后很快停止,先检查系统的电池优化、后台限制和 VPN 权限;如果 iOS 启动后没有流量,先确认系统 VPN 配置仍处于允许状态,并检查 Apple 平台客户端的服务日志入口。界面名称、可用分发渠道和功能会随系统及客户端版本变化,获取方式以官方页面为准。
Windows、macOS 和 Linux:图形客户端与命令行的区别
官方图形客户端列表显示,Android 使用 sing-box for Android,iOS、macOS 和 Apple tvOS 使用 sing-box for Apple platforms,Windows 和 Linux 使用 sing-box for Desktop。官方图形界面客户端列表
- 桌面图形客户端:打开配置管理区域,选择 Remote 或导入 Local JSON。桌面客户端可以管理并运行本地或远程配置;官方页面列出的 sing-box for Desktop 支持 Windows 10+ 与 Linux,并提供 TUN 等平台功能。查看桌面客户端说明
- 命令行核心:先把远程配置下载为本地 JSON,再检查配置,而不是直接把订阅 URL 当作配置文件参数。配置检查命令为
sing-box check -c config.json;官方配置文档同时提供了格式化与合并命令。查看官方配置命令 - 配置检查通过后再启动:如果使用命令行,先确认配置文件路径、工作目录和权限,再启动 sing-box。检查失败时不要直接修改多个字段,先根据错误行号定位 JSON 括号、逗号、字段名或字段类型。
- 系统代理与 TUN 分开判断:浏览器能用但其他应用不能用,可能只是系统代理生效;全部应用都不能用,则继续检查 TUN、管理员权限、系统防火墙和 DNS。不要同时打开多个代理客户端,否则本地端口和路由可能互相覆盖。
本地配置适合需要手动编辑或固定文件的场景;Remote 配置适合由订阅提供方维护内容并定期更新的场景。二者不是同一个对象:Remote 保存的是更新来源,Local 保存的是本地 JSON 内容。远程配置更新后,如果字段与当前客户端支持范围不一致,可能出现更新成功但启动失败,因此应在每次大幅变更后查看日志。
导入后没有节点、无法联网或解析失败:按顺序排查
| 现象 | 优先检查 | 处理方法 |
|---|---|---|
| Remote 保存失败或无法下载 | URL 是否完整、网络是否能访问、链接是否过期 | 重新复制完整 URL;用浏览器或命令行确认返回是否仍为 JSON;向提供方确认订阅是否需要认证 |
| JSON 解析错误 | 返回内容是不是 HTML、YAML 或错误提示 | 不要直接改成 JSON 后缀;重新索取 sing-box 格式,或保存实际返回内容后检查括号、引号和逗号 |
| 配置能更新但启动失败 | 字段是否被当前客户端支持、版本是否过旧 | 查看日志中的字段名和行号;用 sing-box check -c config.json 检查本地文件;必要时让提供方生成兼容配置 |
| 配置成功但没有节点 | 是否只有出站模板、Selector 是否引用了不存在的 tag | 查看 outbounds 和分组关系;检查配置是否包含可用的节点出站,而不是只有 route 或 DNS |
| 客户端显示运行但应用无法联网 | VPN/TUN 权限、系统代理、DNS、后台限制 | 先关闭其他代理软件,重新授权 VPN;再查看 DNS 请求和连接日志,最后检查 TUN 或系统代理模式 |
| 部分网站或应用异常 | 规则、DNS、IPv6、MTU 或应用绕过设置 | 先切换到明确的单节点或直连测试,再逐项恢复规则;不要一次修改 DNS、MTU 和路由多个变量 |
推荐排查顺序:格式 → URL 可达性 → 配置解析 → 节点或出站组 → VPN/TUN 权限 → 系统代理 → DNS → 规则。每完成一层就测试一次,这样能知道问题发生在哪一层。若使用 Android,还要检查电池优化和后台活动限制;若使用 Apple 平台,可从设置中的服务日志查看运行信息。Apple 日志入口说明 Android 客户端说明
订阅安全与更新维护清单
- 把订阅当作凭据:URL 可能包含 token 或其他访问信息,不要公开分享、上传到代码仓库或放进截图。
- 优先使用原始配置:如果提供方能直接生成 sing-box JSON 或 Remote URL,优先使用该格式;第三方转换服务不是导入 sing-box 的必需环节。
- 更新前保留可回退配置:在 Remote 更新前导出或保存当前可用的 Local JSON;更新后如果无法启动,可以回退并对比变化。
- 定期检查更新结果:自动更新不是自动修复。每次更新后确认配置仍能解析、节点组仍有成员、服务仍能启动。
- 链接疑似泄露时:尽快在订阅提供方后台重置或重新生成链接,并在客户端删除旧 Remote Profile;具体操作以提供方页面为准。
截至 2026-11-14 查阅,官方文档仍将 sing-box 配置定义为 JSON,并分别维护图形客户端、远程配置和平台特性说明。客户端版本、应用分发渠道与界面文字可能变化,下载和版本选择以官方页面为准。
常见问题
sing-box 订阅链接和 JSON 配置是一回事吗?
不是。订阅链接是获取配置的地址,JSON 是配置内容;Remote Profile 保存 URL,Local Profile 保存本地 JSON。能否导入取决于链接返回内容和客户端支持范围。
sing-box 导入订阅后为什么没有节点?
先确认返回内容是否为完整 sing-box 配置,再检查 outbounds 是否包含节点、Selector 或 URLTest 是否引用了存在的 tag。只有规则或 DNS 配置时,不一定会出现可选节点。
sing-box 订阅更新失败怎么办?
依次检查 URL 是否完整、订阅是否过期、网络是否可达、返回内容是否为 JSON,以及客户端日志中的错误。不要先修改多个配置字段,先确认是下载失败还是解析失败。
sing-box 启动后没有网络,应该先查什么?
先确认 VPN 或 TUN 权限,再关闭其他代理客户端,检查系统代理、DNS 和后台限制;如果只有部分应用异常,再检查规则、应用绕过设置和 IPv6。
可以把其他客户端订阅直接导入 sing-box 吗?
不能默认认为可以。YAML、节点分享链接和其他客户端专用订阅的字段结构可能不同,应先向订阅提供方确认是否提供 sing-box JSON 或 Remote 格式。