sing-box 导入订阅教程：远程 URL、本地 JSON 与常见错误排查
简答：sing-box 导入订阅的关键是先确认订阅内容是否为 sing-box 可读取的 JSON 配置。远程订阅应使用 Remote Profile，填写 Name 和 URL；本地配置则导入 JSON 文件。Base64 节点列表或 Clash YAML 不能默认直接当作 sing-box 配置使用，格式不兼容时应向提供方索取 sing-box 专用订阅，或在确认第三方转换服务可信后再转换。
定义：sing-box 订阅通常指一个可被客户端读取的远程 sing-box JSON 配置地址，客户端将其保存为 Remote Profile 并按设置更新；本地 JSON 文件则属于 Local Profile。
一、导入前先确认订阅格式
sing-box 的图形客户端管理的是本地或远程 sing-box 配置文件。官方文档将远程配置定义为以 URL 作为更新来源的 Remote Profile，并说明图形客户端应支持自动更新以及 HTTP Basic 认证。可参考sing-box 图形客户端通用说明。
因此，拿到订阅链接后，不要只看链接后缀，建议先确认服务提供方是否明确写有“sing-box 专用”“sing-box JSON”或类似说明。常见情况如下：
- sing-box JSON 配置：通常可以作为远程 URL 或本地 JSON 文件导入，但仍需通过客户端配置校验。
- Clash YAML：属于另一种配置格式，不能默认直接作为 sing-box JSON 导入。
- Base64 节点列表：通常只是编码后的节点文本，不等于完整的 sing-box 配置文件。
- 单个节点链接：例如某种协议分享链接，通常需要手动转换为 sing-box 出站配置，不能直接当作完整订阅配置。
如果格式不明确，优先向订阅提供方索取 sing-box 专用订阅链接。也可以使用订阅转换思路生成 sing-box JSON，但第三方转换服务可能会接触完整订阅地址、节点信息或访问凭据，尤其是带有用户标识的 URL，不建议随意提交给不熟悉的服务。
二、Android 导入远程订阅
官方 Android 客户端 SFA 可以管理和运行本地或远程 sing-box 配置文件，并可在需要时使用 Android 的 VPN Service 实现 TUN。官方文档列出的 Android 系统要求为 Android 5.0 及以上，详情见sing-box for Android 官方说明。
- 打开 sing-box for Android，进入配置文件或 Profile 管理页面。
- 点击新增配置，选择创建远程配置的入口；不同版本的菜单布局可能略有变化，但目标应是新建 Remote Profile，而不是创建空白 Local Profile。
- 在 Name 中填写容易识别的名称，例如“个人订阅”。
- 在 URL 中粘贴 sing-box 专用订阅地址。不要把网页首页、登录地址或仅返回文本说明的链接当作配置地址。
- 如果客户端提供自动更新选项，可按需要开启，并设置更新间隔；首次排查问题时建议先手动更新，确认 URL 能返回有效 JSON 后再开启自动更新。
- 保存配置，打开配置详情或编辑器检查内容，再启动服务。Android 首次启用 TUN 时，需要按系统提示允许 VPN 权限。
如果 Android 中只有“导入文件”而没有明显的远程入口，先更新到当前可用版本，并从配置管理页面寻找 Remote Profile。官方客户端的功能会随版本调整，具体按钮名称以当前安装版本显示为准。
三、iPhone、iPad 与 macOS 导入订阅
sing-box for Apple platforms 支持管理和运行本地或远程配置文件。官方页面显示，iOS 要求为 iOS 15.0 及以上，macOS 要求为 macOS 13.0 及以上；macOS 还提供独立版本。可先查看Apple 平台官方客户端说明。
方法一：通过 Remote Profile 手动添加
- 打开客户端，进入 Profile 页面，点击新增配置或“New Profile”。
- 选择“Create Manually”，进入新建配置页面。
- 将配置类型设为 Remote。
- 在 Name 中填写配置名称。
- 在 URL 中粘贴 sing-box JSON 订阅地址。
- 根据需要打开自动更新，并设置更新间隔。官方通用说明给出的默认更新间隔为 60 分钟，但具体界面和版本设置仍以当前客户端为准。
- 保存后返回配置列表，选中该 Profile，先执行更新或查看配置内容，再启动服务。
方法二：导入本地 JSON 文件
- 在“New Profile”页面选择“Import from File”。
- 选择扩展名为
.json的 sing-box 配置文件。 - 确认导入的配置名称和内容，保存后选中该 Profile。
- 启动前检查配置是否能通过客户端校验；如果出现 JSON 解析错误，先用文本编辑器检查括号、引号、逗号和字段拼写。
Apple 客户端源码中的新建配置菜单包含“Import from File”“Scan QR Code”和“Create Manually”等入口；远程 Profile 的通用定义和更新机制则以官方客户端文档为准。菜单路径可能因 iOS、macOS 版本不同而变化。
四、Windows 与 Linux 怎么导入
截至 2026-10-18，官方已经提供 sing-box for Desktop，支持管理和运行本地或远程 sing-box 配置文件，并提供 TUN 等平台功能。官方页面列出的系统包括 Windows 10 及以上，以及 Linux x64、arm64 和 armv7l，详情见sing-box for Desktop 官方说明。
- 安装当前可用的官方桌面客户端，打开配置管理页面。
- 选择新增 Profile，优先使用 Remote 类型导入订阅 URL；如果手里是文件，则选择本地文件导入。
- 远程配置填写 Name 和 URL，保存后执行更新。
- 选中配置并启动服务；如系统弹出网络权限或防火墙提示，按实际需求处理。
- 如果桌面客户端没有显示远程配置入口，也可以使用 sing-box 命令行程序加载本地 JSON 配置，但命令行参数和配置校验应以当前版本官方文档为准。
不要把 Android、iOS 或 macOS 的菜单路径直接套用到 Windows、Linux。桌面客户端的界面与移动端不同，且部分版本仍可能处于快速迭代状态。
五、Base64 或 Clash YAML 不能导入时怎么办
这是 sing-box 导入订阅中最常见的格式问题。解决顺序建议如下：
- 先确认原始格式：询问提供方这条链接返回的是 sing-box JSON、Clash YAML、Base64 节点列表，还是单个节点链接。
- 优先索取专用链接：如果提供方同时提供多个客户端选项，选择 sing-box、SFA 或 sing-box JSON，而不是 Clash、V2Ray 或通用 Base64 选项。
- 本地检查返回内容：在浏览器或文本编辑器中查看响应是否为 JSON。JSON 通常以
{或[开头，但仅凭开头字符不能完全证明配置有效。 - 需要转换时保护订阅安全：第三方转换服务可能记录订阅 URL。转换前应确认服务来源、隐私政策和数据处理方式；不要在不可信网站提交包含账户标识的订阅地址。
- 转换后重新校验：生成的文件必须符合 sing-box 配置结构，至少不能只是节点列表。导入后如果客户端提示缺少字段、JSON 无效或配置无法启动，应回到转换源检查协议、TLS、DNS、路由和出站字段。
如果只有 Base64 节点列表而没有完整配置，单纯解码并不能保证得到可直接运行的 sing-box 配置；还需要将节点整理到正确的 outbounds、route、dns 或其他必要字段中。
六、导入成功但无法连接的排查顺序
- 先看配置能否更新：如果 Remote Profile 更新失败，先在当前网络下确认 URL 是否可访问、是否需要 HTTP Basic 认证，以及服务器是否返回 JSON。
- 再看配置能否校验：配置内容能显示不代表一定能启动。检查 JSON 语法、字段名称、协议类型和必填字段。
- 检查是否选中了正确 Profile：很多客户端可以保存多个配置，导入成功后还需要把新配置设为当前配置。
- 检查系统权限：Android、iOS 和 macOS 使用 TUN 或 VPN 功能时，系统可能要求授予 VPN、网络扩展或相关权限。
- 检查 DNS 与路由：配置启动但部分网站打不开时，重点查看 dns、route、tun 和出站选择；不要一开始就频繁更换节点或修改大量字段。
- 查看日志：重点关注 JSON parse、unknown field、missing required field、DNS lookup failed、TLS handshake 和 timeout 等错误关键词。
- 逐项恢复：如果配置经过手动编辑，先恢复到提供方原始版本，再一次只改一个字段，便于定位问题。
sing-box 官方客户端文档将 TUN 作为移动平台实现透明代理的重要方式，但不同平台对 TUN 字段和权限的支持并不完全相同。遇到启动异常时，应优先使用适配当前平台的配置，而不是直接复制其他系统的完整配置。
七、导入方式对比表
| 方式 | 适用内容 | 优点 | 常见问题 |
|---|---|---|---|
| Remote Profile | sing-box JSON 远程 URL | 便于后续更新 | URL 返回格式错误、链接失效或需要认证 |
| Local Profile | 本地 sing-box JSON 文件 | 便于离线检查和修改 | 文件语法错误、字段不兼容或版本差异 |
| Clash YAML | Clash 配置文件 | 适用于对应客户端 | 不能默认直接作为 sing-box JSON 导入 |
| Base64 节点列表 | 编码后的节点文本 | 便于传输 | 解码后仍可能缺少完整 sing-box 配置结构 |
八、实用的最短操作清单
如果你只想快速完成一次导入，可以按下面顺序操作：
- 确认链接是 sing-box 专用 JSON 订阅。
- 在客户端新增 Remote Profile。
- 填写 Name 和 URL。
- 保存后手动更新一次。
- 检查配置内容并选中该 Profile。
- 按系统提示授予 VPN 或 TUN 权限。
- 启动服务，失败时先看日志，不要直接反复转换订阅。
如果你手里只有 Base64 或 Clash YAML，最稳妥的下一步不是反复点击导入，而是先获取 sing-box 专用订阅；无法获得时，再评估可信的本地转换方案。
如需继续处理客户端导入后的连接问题，可参考Clash Verge Rev 导入订阅与连接排查教程中的通用排查思路；其中客户端菜单并不适用于 sing-box，但网络、权限和配置核验的顺序具有参考价值。
九、补充说明与参考资料
本文是第三方使用指南，不是 sing-box 或任何订阅服务的官方页面。客户端名称、菜单和可用版本可能随软件更新调整；下载入口、版本要求与功能变化请以官方文档为准。
主要参考：sing-box 图形客户端通用说明、sing-box for Android、sing-box for Apple platforms、sing-box for Desktop。
常见问题
sing-box 可以直接导入 Base64 订阅吗？
不能默认直接导入。Base64 通常只是编码后的节点列表，不一定是完整的 sing-box JSON 配置。建议先向提供方索取 sing-box 专用订阅；如果必须转换，应注意第三方转换服务可能泄露订阅地址和节点信息。
Clash YAML 能不能直接放进 sing-box？
通常不能直接作为 sing-box 配置使用。Clash YAML 与 sing-box JSON 的结构不同，需要获得 sing-box 专用版本或进行格式转换。转换后仍要检查 JSON 语法、协议字段、DNS、路由和出站配置。
sing-box 导入远程 URL 后为什么没有节点？
常见原因包括 URL 返回的不是 sing-box JSON、订阅需要登录或认证、远程服务器返回错误页面、配置没有有效的 outbounds，或者导入后没有选中当前 Profile。建议先手动更新并查看配置内容和日志。
Remote Profile 的自动更新间隔怎么设置？
在支持该功能的图形客户端中，编辑或创建 Remote Profile 时可以设置自动更新和更新间隔。官方通用说明给出的默认更新间隔为 60 分钟，但具体选项和界面以当前客户端版本为准。
Windows 和 Linux 没有手机端那种导入路径怎么办？
使用官方 sing-box for Desktop 的配置管理功能，新增 Remote Profile 并填写 Name、URL；也可以使用命令行加载本地 JSON。Windows 和 Linux 的界面与 Android、iOS、macOS 不同，不要照搬移动端菜单路径。