sing-box 订阅导入失败怎么解决？按状态码、格式和版本逐步排查
简答：sing-box 订阅导入失败，先不要急着重装客户端：先确认订阅链接实际返回的 HTTP 状态码和内容，再判断是链接失效、格式不兼容、配置校验失败，还是导入成功后的节点连接问题。本文不判断某个服务当前是否大面积故障；如果怀疑远端异常，应查看服务方公告或状态页。sing-box 官方配置使用 JSON，远程配置管理能力则取决于所用图形客户端和版本。
定义：sing-box 订阅导入失败，是指客户端无法下载、解析、校验或启动远程配置，不等同于节点已经出现但无法连接。
先看报错：用 5 分钟确定故障在哪一层
大家说的“sing-box 订阅导入失败”，实际可能发生在五个不同阶段：链接下载失败、返回格式不对、JSON 配置校验失败、配置保存后内核启动失败，或者配置已经导入但节点无法连接。sing-box 官方文档明确说明其配置文件使用 JSON，并提供 sing-box check 检查配置；因此，第一步不是反复点击“更新”，而是先确认订阅返回内容。
| 现象或报错 | 优先判断 | 先做什么 | 成功判据 |
|---|---|---|---|
| 403、401、404、410 | 权限、链接撤销或地址失效 | 重新登录服务面板，重新复制或生成订阅链接 | 返回 2xx，并且内容不再是错误页 |
| timeout、connection refused、TLS error | 当前网络、DNS、TLS 或远端不可达 | 换一个已获批准的网络测试，并记录完整报错 | 能稳定下载响应内容 |
| invalid character、JSON parse error | 返回内容不是合法 JSON，可能是 HTML、登录页或其他格式 | 保存响应正文，查看前 300 个字符 | 正文是 JSON 对象而不是网页或错误文本 |
| 配置保存成功但启动失败 | 字段、版本或平台能力不兼容 | 查看 Core 日志，使用本机同版本命令校验 | 配置校验通过且内核进入运行状态 |
| 节点显示但无法连接 | 已不是订阅导入问题 | 单独排查节点、DNS、TUN、权限和路由 | 至少一个节点完成连接测试 |
先试这一步：在浏览器中打开订阅地址，或用命令行保存响应。浏览器显示登录页、验证码页、JSON 错误或空白内容时，不要直接把该地址粘贴进 sing-box。
第一步：检查订阅链接是否返回正确内容
订阅 URL 往往包含账号或 Token，不要发到群聊、工单截图或公开代码仓库。先在自己的设备上执行以下命令，命令会把响应头保存为 headers.txt，把正文保存为 response.txt。
read -r -p '请输入订阅 URL: ' SUB_URL
curl -L -D headers.txt -o response.txt --max-time 20 "$SUB_URL"
printf '\n--- response headers ---\n'
sed -n '1,20p' headers.txt
printf '\n--- response preview ---\n'
head -c 300 response.txt
printf '\n'Windows PowerShell 可使用：
$SUB_URL = Read-Host "请输入订阅 URL"
Invoke-WebRequest -Uri $SUB_URL -MaximumRedirection 5 -TimeoutSec 20 -OutFile response.txt
Get-Content response.txt -TotalCount 10- 返回 2xx：说明 HTTP 请求基本成功，但仍要继续确认正文格式。
- 返回 401 或 403：通常需要重新登录、重新生成订阅，或确认该链接是否需要特定权限；不要靠改客户端参数绕过认证。
- 返回 404 或 410：可能是地址被撤销、路径改变或订阅已失效，应回到服务方账户页面重新复制。
- 超时、连接拒绝或 TLS 错误：先记录发生时间、网络类型和完整报错，再换一个你有权限使用的网络进行对照，不要直接认定远端服务已停止。
如果订阅 Token 曾经公开，最稳妥的处理是立即在服务方页面撤销旧链接并生成新链接。本文无法核实任何具体服务的当前状态，链接是否有效应以服务方页面或公告为准。
第二步：判断返回的是 sing-box JSON、其他格式还是网页
sing-box 官方配置文档给出的配置结构以 JSON 为基础，常见顶层字段包括 log、dns、inbounds、outbounds 和 route。官方还提供 JSON Schema，可用于编辑器补全和配置校验。参考：sing-box 配置介绍、sing-box JSON Schema。
| 响应内容特征 | 含义 | 处理方式 |
|---|---|---|
以 { 或 [ 开头，内容是结构化 JSON | 可能是 sing-box 配置，但仍需校验字段 | 保存为本地 JSON，再使用同版本 Core 检查 |
以 <html、<!DOCTYPE 或登录页文字开头 | 返回了网页、登录页或错误页 | 重新登录或重新生成订阅，不要把网页当配置导入 |
内容是一长串字母数字，夹杂 +、/、= | 可能是 Base64 或分享链接集合 | 确认服务方是否明确提供 sing-box JSON 格式；不要假定可直接导入 |
出现 YAML 缩进、proxies:、proxy-groups: | 更像 Clash YAML | 使用明确支持该格式的转换或客户端入口，不能直接当作 sing-box JSON |
| 正文为空或只有错误文本 | 订阅生成异常、权限失败或接口返回不完整 | 保存响应并向服务方提交状态码和时间，不要公开 Token |
格式判断只能说明“服务器返回了什么”，不能证明节点一定可用。即使 JSON 能解析，也可能没有有效的 outbounds、缺少路由，或包含当前 Core 不认识的字段。
第三步：本地校验配置，并处理版本兼容
如果已经拿到本地 JSON 文件，可以使用与客户端实际运行版本一致的 sing-box Core 检查。官方配置文档提供了 sing-box check 和 sing-box format 命令；不要用一个版本下载配置、再用另一个版本盲目判断结果。
sing-box version
sing-box check -c response.json
sing-box format -w -c response.json其中：
sing-box version：记录当前 Core 版本。sing-box check -c response.json：检查配置结构和字段是否能被当前 Core 接受。sing-box format -w -c response.json：按 sing-box 格式整理 JSON；执行前建议复制一份备份。
如果命令提示未知字段、弃用字段或字段类型错误，先不要手动删除大量内容。打开官方迁移说明，对照当前版本逐项修改。官方迁移页面显示，部分配置字段会在不同版本中弃用、改名或移除；例如某些 TUN、DNS 和路由字段存在版本边界。可参考：sing-box Migration。
回滚方法：保留原始订阅响应和旧配置副本，修改后的文件另存为新文件；如果升级客户端后才失败，暂时回到原来能运行的版本或配置，并以官方发布说明核对变化。当前可用版本和稳定性不能仅凭本文判断，应以 sing-box 官方 Releases 为准。
第四步：按客户端入口重新导入，而不是重复覆盖旧配置
不同图形客户端的菜单名称可能不同，但排查逻辑一致：删除明显失败的远程配置条目，重新创建一个远程配置，粘贴新链接，保存后手动更新，再查看日志。官方桌面客户端说明其用途包括管理和运行本地或远程 sing-box 配置文件；如果你使用的是其他客户端，入口名称和支持格式需以该客户端说明为准。参考：sing-box Desktop 官方文档。
- 先记录当前版本：记录客户端版本、Core 版本、操作系统和完整报错。
- 保留旧配置：导出或复制旧配置，避免删除后无法比较。
- 新建远程配置：选择“远程配置”“Remote Profile”或同义入口，不要把订阅 URL 粘贴到本地 JSON 编辑框。
- 粘贴新链接并保存：检查前后没有空格、换行或截断；如果链接带 Token，不要截图分享。
- 手动更新一次：观察下载状态、返回码和日志，不要连续点击更新。
- 确认成功：配置列表中出现配置，节点列表有可识别条目，Core 日志没有 schema、parse 或 unknown field 错误。
如果客户端只提供 Clash、Base64 或其他格式入口，而服务方只给了 sing-box JSON，格式不匹配就是高概率原因。此时应获取明确标注为 sing-box 的订阅，或使用经过信任、能说明输入输出格式的转换流程；不要把“能下载”误判为“能导入”。
第五步：导入成功但无节点、只有 DIRECT 或无法连接
出现配置名称不代表节点已经可用。可以按以下顺序分流：
- 配置列表为空：优先检查远程配置是否保存成功，以及更新时是否返回了非空 JSON。
- 只有 DIRECT：检查响应正文是否实际包含出站配置；如果只有基础模板或路由，没有有效节点，应重新获取正确订阅。
- 节点有名称但无法连接：这已经进入节点、DNS、TLS、路由或权限排查，不要继续反复导入订阅。
- 桌面端启动失败：查看 Core 日志中的第一条 error，优先处理最早出现的字段、端口、权限或证书错误。
- 开启 TUN 后网页打不开：先关闭 TUN，仅用系统代理或客户端提供的普通代理模式验证节点；如果普通代理可用而 TUN 不行，再检查系统权限、虚拟网卡、DNS 劫持和路由。
官方日志配置支持 trace、debug、info、warn、error 等级，并可输出到文件。排查时先使用客户端提供的日志面板；如果需要修改配置，保留原文件并避免把包含订阅 Token 的日志公开。参考：sing-box Log 官方文档。
一张排障清单：什么时候该停止重试
- HTTP 状态不是 2xx：先解决链接、权限或远端接口问题。
- HTTP 成功但正文是 HTML：先解决登录、认证或订阅生成问题。
- 正文是其他格式：确认是否有明确的 sing-box JSON 订阅，不要强行导入。
- JSON 能打开但
sing-box check失败：核对 Core 版本和迁移说明。 - 配置校验通过但启动失败：查看第一条 Core 错误，检查端口、权限、证书和字段。
- 节点出现但连接失败：转入节点、DNS、路由、TUN 和系统网络排查。
- 链接曾公开：撤销旧 Token，重新生成订阅，并删除公开位置的链接。
如果你已经完成以上检查，仍无法判断问题在本地还是远端，可向服务方提供客户端版本、Core 版本、HTTP 状态码、响应类型和脱敏后的错误文本，但不要提交完整订阅 URL。
常见问题
sing-box 订阅链接能在浏览器打开，为什么客户端仍然导入失败？
浏览器能打开只说明请求得到了响应，不代表返回的是 sing-box JSON。浏览器可能显示登录页、HTML 错误页、Clash YAML 或其他格式。请保存响应正文并检查是否为合法 JSON，再用同版本 Core 执行 sing-box check。
Clash 订阅可以直接导入 sing-box 吗？
不能默认认为可以。Clash YAML、Base64 分享内容和 sing-box JSON 的结构不同；是否能转换取决于客户端或转换工具的明确支持。优先获取服务方明确标注为 sing-box 的订阅格式，不要仅凭链接能下载就判断兼容。
sing-box 导入后只有 DIRECT，没有节点怎么办？
先检查订阅响应是否为空、是否返回基础模板或错误页，再确认配置中是否存在有效的 outbounds。若 JSON 校验通过但没有节点，通常应重新获取正确的订阅链接，而不是修改 DNS 或反复重装客户端。
sing-box 报 unknown field，应该删掉报错字段吗？
不要直接批量删除。先记录 Core 版本，再查看官方 Migration 说明，确认字段是拼写错误、版本弃用还是平台不支持。修改前复制原配置，修改后使用同版本 sing-box check 验证。
订阅 Token 泄露后怎么处理？
立即在服务方页面撤销旧订阅或重新生成链接，删除公开位置的旧链接，并在客户端替换为新地址。不要把完整订阅 URL、二维码或带 Token 的日志发到公开渠道。