sing-box 订阅更新失败怎么办？按错误类型逐步排查
简答：先保留旧配置并复制备份，再确认订阅链接是否完整、HTTP 返回是否正常、响应正文是否为 sing-box 可解析的 JSON。若返回 403、404、429 或 HTML，优先检查链接、权限、限流和登录页；若请求成功但出现 JSON parse error 或 schema error，再检查格式与 sing-box 内核版本。
定义：sing-box 订阅更新失败，是指客户端无法从远程 URL 获取配置、无法解析响应内容，或解析后因字段与当前内核不兼容而不能加载。
先做这一步：保留旧配置，确认故障处在哪个阶段
本文是面向 sing-box 使用者的第三方使用指南，不代表任何客户端或订阅提供方。订阅更新失败不一定等于节点失效，至少要区分四个阶段：订阅请求、内容解析、内核加载和节点连接。先停止反复点击更新，保存当前可用配置或导出本地配置，并把原始订阅链接放在密码管理器等私密位置；订阅 URL 可能包含 Token，不要粘贴到公开 Issue、群聊或截图中。
| 现象 | 先查什么 | 判断标准 | 下一步 |
|---|---|---|---|
| 404、403、429、5xx | 链接、权限、限流和服务端响应 | HTTP 状态码异常 | 核对链接和账号状态，等待限流窗口，必要时向订阅提供方核实 |
| timeout、TLS、DNS error | 当前网络、系统代理、DNS、IPv4/IPv6 | 请求没有得到有效正文 | 切换网络复测，检查系统时间与代理链路 |
| HTML、登录页、空文本 | 重定向、登录验证、User-Agent 或防护页面 | 正文不是 JSON 配置 | 不要把浏览器能打开当作客户端可解析，确认真实响应 |
| JSON parse error、schema error | 配置格式、字段和内核版本 | 已拿到正文但无法加载 | 备份后检查 JSON、字段迁移和版本兼容 |
| 更新成功但节点不能连接 | 路由、DNS、TUN、协议参数 | 配置已加载，连接阶段失败 | 转入连接排查，不要继续刷新订阅 |
sing-box 图形客户端将远程配置视为 Remote Profile，远程地址是配置的更新来源；官方文档也说明图形客户端应支持自动更新和 HTTP Basic 认证，但不同平台的菜单名称可能不同，实际界面应以当前客户端为准。可参考sing-box 官方图形客户端说明。
用浏览器、curl 或 PowerShell 检查 HTTP 状态和正文首行
- 先检查链接本身：确认没有复制换行、空格、引号或截断字符，账号没有到期，Token 没有被重置。不要把完整 URL 发给他人；以下命令中的
SUBSCRIPTION_URL只是占位符。 - Linux、macOS 或已安装 curl 的 Windows：
curl -L --max-time 20 -D headers.txt -o response.txt "SUBSCRIPTION_URL"。查看headers.txt中的状态码和response.txt首行，确认响应是否为空、是否以 HTML 或登录页开头。 - PowerShell：
$r=Invoke-WebRequest -Uri "SUBSCRIPTION_URL" -MaximumRedirection 5 -TimeoutSec 20; $r.StatusCode; $r.Headers; $r.Content.Substring(0,[Math]::Min(200,$r.Content.Length))。不要把包含 Token 的完整命令复制到公开位置。 - 判断结果：200 只代表服务器返回了内容，不代表内容一定是 sing-box 配置；如果正文是登录页面、Cloudflare 等提示页、错误说明或空文本，客户端可能继续报解析错误。
如果浏览器可以打开而 sing-box 仍失败，可能是浏览器已经完成了登录或重定向，而客户端拿到的是另一份响应；也可能是请求需要特定认证方式。此时应对比状态码、最终 URL、Content-Type 和正文首行，而不是只看浏览器页面。
若出现 403，先核对权限、账号状态、访问来源和订阅地址；404 通常应优先检查 URL 是否过期或复制错误；429 表示需要减少重复请求并等待；5xx 或持续超时应记录时间、网络环境和响应结果，再向提供方核实。没有服务端证据时，不要把某个状态码直接归因于线路故障。
按错误关键词处理：格式、版本和网络分别排查
1. JSON parse error：响应不是合法 JSON
先打开保存的响应文件，只查看开头和结构，不要公开完整内容。若第一行是 <!DOCTYPE html>、登录提示、错误页面或空文本，问题在订阅请求或返回内容，不是 sing-box 节点参数。若正文像 YAML、URI 列表或其他客户端专用格式，也不能直接假定 sing-box 可以加载。sing-box 配置使用 JSON Schema 进行结构描述，官方文档提供了配置 Schema 和生成命令，可查看sing-box 官方 JSON Schema 文档。
2. schema error：JSON 有效，但字段不符合当前配置结构
这类错误通常需要结合日志中的字段名判断。先备份旧配置，再对照当前内核对应的官方配置文档；不要只删除报错字段，因为字段可能承担 DNS、路由或安全校验功能。若你刚升级过 sing-box，优先查看迁移说明，尤其是 DNS server 格式、已弃用字段和 rule-set 变化。官方迁移页记录了 1.12.0、1.14.0 等版本的配置变化，参见sing-box 官方迁移文档。
3. timeout、TLS 或 DNS error：先验证订阅地址是否能访问
先暂时关闭会改变出站路径的系统代理、TUN 或其他 VPN 组件，再用另一网络测试订阅请求；记录切换前后的状态码和耗时。若只有某个网络失败，可能与 DNS、IPv4/IPv6、网络切换或代理更新链路有关，但不能仅凭一次失败确定根因。检查系统日期和时间是否正确，确认订阅域名能够解析，并避免在失败时连续刷新造成更多限流。
4. 更新成功但空节点或无法连接：不要混同为订阅更新失败
如果客户端已经显示配置载入成功，故障阶段可能已经进入内核加载或节点连接。此时检查配置中是否真的有出站、选择器或节点，查看日志中的协议、TLS、DNS 和路由错误；不要重复更新订阅。TUN、系统代理和 DNS 修改应在确认适用平台、已有备份并了解恢复方式后进行，不能作为所有更新失败的默认解法。
版本兼容：先确认客户端、内核和配置来源
sing-box 有命令行内核和不同平台的图形客户端，界面版本、内核版本以及打包方式可能不同。排查前记录三项信息：客户端名称、操作系统与架构、客户端显示的 sing-box 内核版本。不要把网上某个 Issue 中的个案直接当成普遍原因。当前可用版本、发行说明和预发布版本应以sing-box 官方 GitHub Releases及客户端自身的版本信息为准；本文不替你指定一个“必须升级到”的版本。
如果升级后才开始报 schema error，先保留旧版本配置和备份文件，再查看迁移文档中对应版本的变化。若配置来自订阅提供方，字段修复通常需要由配置生成方完成；本地强行改动可能导致更新后再次被覆盖。若降级用于验证，应先确认旧版本仍能加载该配置，并避免在没有备份时覆盖原文件。
安全恢复顺序建议是：停止客户端或暂停自动更新；备份当前配置和日志；重新复制或重新生成订阅链接；在不启用 TUN 的条件下测试请求；确认响应正文和格式；再导入或更新；最后恢复原来的代理、DNS 或 TUN 设置。每一步都记录结果，便于判断是网络请求、解析还是运行阶段出了问题。
快速自查清单：什么时候需要向订阅提供方反馈
- 已确认客户端名称、系统平台和内核版本。
- 已备份旧配置，没有直接删除当前可用配置。
- 订阅 URL 没有换行、截断或泄露，账号和 Token 状态已核对。
- 已记录 HTTP 状态码、最终响应类型和正文首行。
- 已区分 403、404、429、5xx、超时、HTML、JSON parse error 和 schema error。
- 已在不启用额外 TUN 或代理链路的情况下复测。
- 如果需要反馈，只提供时间、平台、客户端与脱敏日志，不提供完整订阅 URL、Token 或节点密码。
如果同一订阅在多个网络、多个客户端都返回相同的非 200 状态或相同错误正文，建议把脱敏后的状态码、响应类型、发生时间和客户端版本交给订阅提供方核实。若只有单个平台失败，则优先保留平台、网络和客户端差异，避免直接判断为订阅源失效。
常见问题
sing-box 订阅更新失败，先删除旧配置吗？
不建议。先备份或保留旧配置，确认新订阅已经成功获取并能解析后，再考虑替换。直接删除旧配置会让你失去回滚依据，也可能把订阅请求问题误判为客户端故障。
浏览器能打开订阅链接，为什么 sing-box 还是更新失败？
浏览器可能已经完成登录、跟随了重定向，或使用了不同的请求头。请比较客户端和浏览器获得的 HTTP 状态码、Content-Type、最终地址和正文首行；网页能显示不代表返回内容是 sing-box 可解析的 JSON。
返回 200 但出现 JSON parse error，说明订阅链接有效吗？
只能说明服务器返回了内容，不能证明内容格式正确。响应可能是 HTML、登录页、错误说明、YAML 或其他格式。应保存响应并检查开头内容，同时确认订阅提供的是适用于 sing-box 的配置格式。
sing-box 升级后订阅更新失败怎么办？
先记录升级前后的内核版本，保留旧配置和日志，再查看官方迁移文档中对应版本的字段变化。若错误指向 DNS、rule-set 或其他字段，不要无依据地批量删除配置项，必要时让配置生成方更新订阅模板。
更新成功后仍然无法上网，是订阅更新失败吗？
不一定。若配置已加载并能看到节点，问题可能位于节点连接、DNS、路由、系统代理或 TUN 阶段。此时应查看运行日志和连接测试结果，不要继续反复刷新订阅。