sing-box 订阅怎么导入？配置文件与连接检查
简答：sing-box 订阅导入的关键不是直接粘贴链接，而是先确认它返回的是 sing-box 配置，再建立 Remote Profile；本地 JSON 则建立 Local Profile。导入后按“配置更新—节点出现—核心启动—节点握手—DNS 解析—网页访问”顺序检查，任何一步失败都先停在对应层级排查。
定义：sing-box 订阅是由远程 URL 提供、可被 sing-box 客户端定期更新的配置来源；保存到设备的 JSON 文件则属于本地配置。
先试这一步：判断你拿到的内容能不能直接导入
本文是本项目的独立使用指南，客户端名称、菜单和配置字段可能随平台或版本变化；以下优先采用 sing-box 项目公开文档能够确认的通用概念。
| 你拿到的内容 | 通常应选择 | 导入前检查 | 不能直接做什么 |
|---|---|---|---|
| 远程 URL，返回 sing-box JSON | Remote Profile | 用私密方式确认返回内容是 JSON，而不是登录页、HTML 或错误文本 | 不要把链接公开发到群聊、截图或工单 |
| 本地 .json 文件 | Local Profile | 备份原文件，确认编码和 JSON 结构可解析 | 不要只看扩展名就认定兼容 |
| Clash YAML、Base64 或其他通用订阅 | 先找能输出 sing-box 格式的来源或转换工具 | 确认转换后字段、协议和规则集仍被当前核心支持 | 不能把 Clash YAML 当作 sing-box JSON 直接导入 |
| 单节点链接或二维码 | 按客户端支持情况导入或转成配置 | 确认协议、TLS、传输方式等信息完整 | 不能保证所有客户端都能识别同一种链接 |
官方文档把配置分为 Local、Remote 和 Apple 平台的 iCloud Profile；Remote Profile 以 URL 作为更新来源，并支持自动更新。查看 sing-box Profile 定义
- 返回 JSON：开头通常是
{或[，但仅凭开头不能证明它是可用的 sing-box 配置。 - 返回 HTML：看到登录页、验证码页、403/404 页面或网关错误，先处理订阅权限、地址和网络，不要继续导入。
- 返回 JSON 但解析失败：可能是格式损坏、字段不兼容、复制时多了字符，或它其实是其他客户端格式。
最短导入闭环：Remote 订阅与本地 JSON
- 准备来源。保留订阅 URL 或 JSON 文件原始副本；订阅 URL 往往包含访问凭据，不要在普通浏览器公开打开，也不要把完整链接贴进公开日志。
- 选择配置类型。远程地址选 Remote；本地文件选 Local。官方图形客户端的统一定义中，Remote Profile 的更新来源是 URL，Local Profile 则对应本地配置内容。查看官方 Profile 说明
- 填写最少信息。为配置起一个能识别的平台或用途名称，Remote 中填 URL；如果服务方同时提供 HTTP Basic 用户名和密码，再按客户端提供的授权字段填写。不要把令牌写进文章、截图或命令历史。
- 保存并刷新。保存配置后执行一次更新或刷新，等待客户端完成下载和解析。官方文档说明 Remote Profile 应支持自动更新，默认更新间隔为 60 分钟；实际菜单名称以当前客户端为准。查看 Remote Profile 行为
- 启动服务。选择配置、节点组或出站后启动。Android 客户端在需要 TUN 时通过系统 VpnService 工作；Apple 平台通过 NetworkExtension 提供 TUN 能力，因此首次启动可能出现系统权限确认。查看 Android 官方客户端能力 查看 Apple 平台官方客户端能力
- 按顺序验收。不要把“配置已保存”当成“网络已连通”，继续完成后文的六项检查。
Android、iOS、macOS、Windows 怎么分别操作
| 平台 | 建议路径 | 权限或差异 | 停止条件 |
|---|---|---|---|
| Android | 安装官方图形客户端后，进入配置或 Profile 管理，新增 Remote 或导入 Local，保存、更新、选择出站并启动 | 需要 TUN 时要允许系统 VPN；系统可能限制后台运行或省电策略 | 节点为空、更新返回 HTML、VPN 权限未授予时先不要判断线路问题 |
| iOS | 在 Apple 平台客户端中新增远程配置或导入本地配置，保存后启动 Network Extension | 系统网络扩展权限、后台行为和可用字段受 Apple 平台限制；菜单名称需以当前版本为准 | 配置能解析但扩展无法启动时，先检查系统权限和配置中平台不支持的字段 |
| macOS | 使用 Apple 平台客户端或当前可核验的桌面客户端，新增 Remote/Local Profile 后启动服务 | 独立版、商店版和测试版的发布渠道与设置继承可能不同，不能仅凭客户端名称推断 | 系统扩展未获准、配置字段不支持或服务未启动时，先看日志 |
| Windows | 使用官方客户端列表中对应的桌面客户端，导入 Remote 或 Local 配置，保存后启动并检查状态 | 官方文档将 Windows 客户端列为 sing-box for Desktop；具体安装包、架构和菜单以发布页为准 | 配置解析成功但没有系统代理或 TUN 效果时，检查运行模式和系统权限 |
官方客户端总览列出 Android、Apple 平台以及 Windows/Linux 桌面客户端；该页面也提醒，未列出的项目不能仅因名称含有 sing-box 就认定为官方客户端。查看官方图形客户端列表
Android 官方页面确认其客户端可以管理和运行本地或远程 sing-box 配置；Android 5.0+ 是该页面列出的要求，但具体 APK、系统兼容性和发布渠道仍应以当前官方页面为准。查看 Android 客户端说明
本地 JSON 导入前，先做三项低风险检查
- 确认文件来源。只处理你明确知道来源的配置文件。先复制一份备份，后续编辑或清理前保留原文件。
- 确认是 JSON 而不是 YAML。sing-box 官方提供 JSON Schema；兼容编辑器可以用该 Schema 做补全和校验，当前安装的二进制也可以通过
sing-box schema -o schema.json生成与自身匹配的 Schema。查看官方 JSON Schema 文档 - 确认核心与字段匹配。配置能被编辑器打开，不等于当前客户端核心一定支持其中所有字段。版本迁移、规则集、DNS、TLS 和协议字段都应以当前官方配置文档及客户端日志为准。
不要为了“导入成功”随意删除未知字段。若日志明确指出某个字段不支持，先记录字段名、客户端版本和核心版本，再对照官方文档修改；改动后保留原始文件，便于回退。
导入后六步连接检查：定位到底是哪一层失败
- 更新成功：Remote Profile 能完成下载，没有 401、403、404、429 或超时。
- 节点出现：配置中存在可选择的出站或分组；如果分组为空，先检查订阅内容和配置结构。
- 核心启动：客户端状态显示服务运行，日志没有 JSON parse error、Schema error 或字段不支持。
- 节点握手：选择一个节点后观察连接是否建立；握手失败优先检查服务器地址、端口、协议、TLS 和本地网络。
- DNS 解析：如果节点似乎已连接但域名打不开，区分 DNS 失败与传输失败。sing-box 官方客户端示例包含 DNS、TUN、路由和 DNS 劫持等配置概念，不能只靠更换节点解决所有问题。查看官方客户端配置示例
- 实际访问：用一个普通网页或你明确有权限访问的业务地址测试；再分别判断浏览器、单个应用和系统全局是否表现一致。
如果第 1 步失败，不要跳到 MTU 或线路测试；如果第 3 步失败，不要先归因于 DNS；如果第 5 步失败，先检查 DNS 与路由，再比较节点。这样可以避免把格式错误误判成网络问题。
常见错误与回退动作速查
| 现象或错误 | 优先判断 | 处理动作 |
|---|---|---|
| 404、403、401 | 地址失效、权限、订阅令牌或访问控制 | 核对 URL、账户状态和授权方式；无法互相印证域名、账户和条款时停止导入 |
| 429 | 请求频率或服务端限流 | 停止连续刷新，稍后按服务方说明更新；不要反复复制令牌到多个客户端 |
| 超时 | 当前网络无法访问订阅地址，或远端响应过慢 | 先换稳定网络并单独验证订阅地址可达性；不要马上修改整份配置 |
| JSON parse error | 返回内容不是合法 JSON，或文件被截断、混入其他字符 | 重新获取原始文件，使用编辑器校验；不要直接手工删除大量内容 |
| Schema 不兼容、字段不支持 | 客户端核心与配置模板版本不匹配 | 记录版本和字段名，对照当前官方文档调整；必要时回退到原文件 |
| 分组为空或没有节点 | 订阅内容为空、转换失败、出站结构不符合当前客户端 | 先查看配置内容和日志，确认确实包含 outbounds 或可用分组 |
| 启动成功但网页打不开 | DNS、路由、系统代理/TUN、权限或目标站点本身 | 按“DNS—路由—权限—应用差异”顺序排查，避免直接改动多个变量 |
订阅安全与版本兼容：什么时候应该停止
订阅 URL 可能包含可访问配置的令牌。假如完整链接被公开发布，应把它当作凭据泄露场景处理：停止继续分享，按照来源方提供的方式重新生成或撤销旧链接，再在客户端替换新地址。日志、截图和报错文本也应遮挡 URL 查询参数、用户名、密码、服务器地址和密钥。
版本方面，不把“最新”当作永久兼容承诺。官方文档持续更新配置字段、JSON Schema 和图形客户端能力；发布页同时可能存在稳定版、预发布版或测试版，因此升级前应同时核对客户端版本、sing-box 核心版本、配置模板版本和规则集版本。无法确认兼容关系时，先备份、再小范围升级，不要直接覆盖唯一可用配置。查看官方更新日志
如果官方页面、客户端日志和配置内容无法互相印证域名、账户、格式或权限，最稳妥的动作是停止下载、付款或继续导入，先向配置提供方核实。
结论：用“格式—配置—核心—握手—DNS—访问”定位
sing-box 订阅导入的最短路径是：先确认返回内容确实是 sing-box JSON，再建立 Remote Profile；本地文件则建立 Local Profile。导入完成后按六层验收，不要把配置保存、核心启动或节点出现误认为已经联网。
需要切换设备或客户端时，优先迁移原始订阅来源和备份配置，不要迁移公开截图中的令牌；需要比较多个节点或线路时，也应先确认客户端和配置本身正常，再进行延迟、丢包或 DNS 排查。
常见问题
sing-box 订阅链接可以直接粘贴到客户端吗？
只有在它返回的是当前核心可解析的 sing-box 配置时才适合直接建立 Remote Profile。若返回 HTML、登录页、Clash YAML、Base64 或错误文本，应先核对来源和格式，不能只看链接后缀。
sing-box 的 Remote Profile 和 Local Profile 有什么区别？
Remote Profile 以 URL 为更新来源，适合需要定期刷新内容的远程配置；Local Profile 对应设备上的本地配置文件，适合手动维护和备份。官方图形客户端还定义了 Apple 平台的 iCloud Profile。
Clash 订阅能不能直接导入 sing-box？
不能把 Clash YAML 直接当作 sing-box JSON 使用。应先确认配置提供方是否能输出 sing-box 格式，或使用可信转换方案，并检查转换后的协议、出站、DNS、规则集和字段是否被当前核心支持。
导入成功但没有节点，应该先查哪里？
先检查 Remote 更新是否成功、返回内容是否为空、配置是否包含 outbounds 或有效分组，再看客户端日志。不要先修改 DNS、MTU 或节点参数，因为节点为空通常还没有进入网络连接排查阶段。
sing-box 启动后还是打不开网页怎么办？
按顺序检查核心是否运行、节点是否完成握手、DNS 是否能解析、TUN 或系统代理权限是否生效，以及目标应用是否使用系统代理。每次只改一个变量，并保留原配置以便回退。
订阅链接泄露了怎么办？
把它按访问凭据处理：停止公开分享，按来源方提供的方式撤销或重新生成订阅，再替换客户端中的旧地址；同时清理公开日志、截图和工单中的完整 URL。