sing-box 连接失败排查：从订阅到网页访问逐步定位
简答：先看失败发生在哪一步：订阅是否下载成功、配置是否启动成功、节点是否完成握手、流量是否真正经过本地入站。然后只改一个变量，完成日志和实际网页访问验证；如果修改后更差，立即恢复备份配置。
定义：sing-box 连接失败排查，是按照订阅获取、配置校验、客户端启动、节点握手、DNS解析和路由访问等阶段，结合日志关键词逐层缩小故障范围的过程。
三步速查：先判断失败发生在哪个阶段
本文是第三方使用指南，只处理已经安装 sing-box 客户端、已有配置后的连接问题，不包含服务端搭建、端口部署或服务商状态判断。
| 现象 | 先验证什么 | 验证后的下一步 |
|---|---|---|
| 订阅下载失败、导入失败 | HTTP 状态、重定向、响应正文和认证状态 | 确认订阅地址有效，再判断返回内容是否为客户端可识别的配置格式 |
| 配置保存后无法启动 | JSON 语法、字段兼容性和配置路径 | 备份旧配置，用当前版本支持的检查命令校验 |
| 客户端显示运行但网页打不开 | 本地入站端口、系统代理、TUN/VPN权限 | 先确认流量进入 sing-box，再检查DNS和路由 |
| 节点超时、被拒绝或握手失败 | 当前协议实际使用的地址、端口、认证和TLS字段 | 按错误关键词分流，必要时在不同网络、不同时间重复验证 |
| 只有部分网站或应用打不开 | DNS规则、route.rules、final出站和分应用设置 | 暂时用明确的代理出站测试，确认是否为分流问题 |
最快的判断顺序是：订阅或配置有没有成功、节点握手有没有成功、网页流量有没有经过本地入站。不要一开始同时修改DNS、TUN、规则集和节点参数。
sing-box使用JSON配置，官方文档提供了配置结构和sing-box check检查入口，可先对照官方配置说明。字段是否可用还取决于当前客户端和内核版本，执行前应查看sing-box --help及对应版本文档。
第一阶段：正确检查订阅地址和响应正文
不要使用只有响应头的curl -I来判断返回内容是否为JSON。-I只发送HEAD请求并获取响应头，部分服务端可能不支持HEAD；需要同时查看状态、重定向、响应头和实际正文时，应使用GET请求。
- 先备份：复制当前配置文件，保存为
config.backup.json，不要覆盖唯一可用配置。 - 下载正文：在Linux或macOS终端执行
curl -L -D subscription.headers -o subscription.body "你的订阅地址"；Windows可使用同样命令的curl，或用浏览器保存响应正文。-L用于跟随重定向，-o保存正文，-D保存响应头。 - 检查结果：查看
subscription.headers中的最终HTTP状态和Content-Type，再打开subscription.body确认是否为完整配置内容。 - 避免误判：401或403、登录页、HTML错误页通常应优先判断为订阅获取、认证、重定向或访问策略问题，但不能仅凭此断言服务端故障。
- 确认格式：部分订阅服务会返回编码内容、转换后的配置或客户端专用格式，不一定直接是 sing-box JSON。只有在当前客户端支持该格式且导入成功后，才能继续检查节点。
如果需要在命令行快速查看正文，可使用curl -L "你的订阅地址"，但不要把包含令牌的完整输出复制到公开工单。订阅令牌、UUID、密码、私钥、认证头和完整节点链接都应脱敏。
curl的-L用于跟随重定向，-o用于保存响应，-I则只获取响应头；具体参数可参考curl官方手册。
第二阶段：配置校验、版本兼容与安全回滚
配置导入成功不代表当前内核一定能启动。先记录版本，再备份、校验、启动，避免在未知状态下反复重启。
- 查看版本和帮助：执行
sing-box version和sing-box --help，确认当前二进制支持哪些命令和参数。 - 检查配置：官方配置文档提供
sing-box check入口；具体配置文件参数、配置目录参数以当前版本帮助为准，不要直接照抄旧教程。 - 出现字段错误：看到
unknown field、deprecated、invalid或JSON解析错误时，只定位报错字段，不要整份配置盲目替换。 - 生成匹配版本的Schema：如果编辑器支持JSON Schema，可用
sing-box schema -o schema.json生成与当前安装版本匹配的Schema，再辅助检查字段。 - 回滚：停止客户端，移出新配置，恢复
config.backup.json，重新载入后再测试。
旧配置中的geoip和geosite在官方文档中已标记为弃用并在较新版本移除，迁移方向是使用rule-set；如果日志明确指向这些字段，再参考官方迁移说明，不要为了“兼容”随意新增字段。
配置检查、Schema生成和字段变化都可能随内核版本变化。执行命令前，以当前版本的--help和官方Schema说明为准。
第三阶段：按错误关键词判断节点、端口还是TLS
| 日志关键词 | 优先排查范围 | 下一步 |
|---|---|---|
timeout、i/o timeout | 地址或端口未及时建立连接，也可能与本地网络、路由或防火墙有关 | 核对当前协议实际使用的地址和端口；在不同网络、不同时间重复测试并保留日志时间 |
connection refused | 目标端口拒绝连接，或地址、端口、协议不匹配 | 只核对配置中实际存在的字段；无法管理服务端时，向配置提供方核实 |
EOF | 连接在握手或传输阶段提前结束 | 检查当前协议对应的传输层、TLS和认证字段，不要强行添加其他协议参数 |
TLS handshake failed、证书错误 | TLS参数、SNI、证书校验或系统时间 | 先确认系统日期时间，再核对配置中实际启用的TLS字段和服务器名称 |
authentication failed、unauthorized | UUID、密码、令牌或认证状态不匹配 | 重新获取配置并检查认证状态，不要公开粘贴完整凭据 |
DNS、no such host | 域名解析失败、DNS上游不可达或规则未匹配 | 先验证系统能否解析该域名，再检查sing-box的DNS服务器、规则和最终出站 |
表格只能缩小范围，不能据此断言某个节点或服务端一定失效。某次超时只说明这次连接没有在规定时间内完成；如果要提高判断质量，应至少在不同时间或不同网络重复验证，并保留客户端版本、错误关键词和日志时间。
地址、端口、UUID、密码、TLS、SNI和传输层并不是所有出站协议都通用。只核对当前配置实际使用的协议字段，不要把其他协议的参数直接复制进去。
第四阶段：客户端显示运行但网页仍打不开
运行状态只能说明进程或VPN状态已启动，不等于浏览器流量已经进入正确的入站、经过预期路由并到达选中的出站。按下面顺序检查。
- 确认本地入站：检查配置中的HTTP或SOCKS入站地址、端口，与系统代理设置是否一致；出现
bind、listen或address already in use时，优先处理端口占用。 - 确认系统代理：Windows和macOS可能保留其他代理软件的手动代理设置。先关闭冲突软件，或暂时只保留一个代理入口。
- 确认TUN或VPN权限：Android、iOS和桌面图形客户端可能需要系统批准VPN权限。权限被撤销时，重新批准后再测试。
- 确认路由：检查
route.rules和route.final。如果规则将目标分到直连，网页可能不会经过代理；先用明确的代理出站做单变量测试。 - 确认DNS：只有在日志或测试明确指向解析失败时，再检查DNS服务器、DNS规则、默认DNS和规则对应的出站。
官方Route文档说明，final用于指定默认出站，auto_detect_interface可用于TUN场景下绑定默认网卡并避免路由环路；这些字段是否适用仍取决于平台和当前版本。可参考官方Route文档。
官方DNS文档说明，dns.final用于指定默认DNS服务器；DNS规则顺序和动作会影响实际解析路径。可参考官方DNS文档和官方DNS规则文档。
平台差异：只检查当前系统真正相关的项目
| 平台 | 优先确认 | 回滚动作 |
|---|---|---|
| Windows | 系统代理、TUN权限、本地端口占用和其他代理软件 | 恢复原系统代理设置，退出客户端后重新载入备份配置 |
| macOS | 网络服务代理、VPN权限、默认网卡和DNS修改工具 | 关闭代理或VPN配置，恢复原网络服务设置 |
| Android | VPN权限、另一个VPN、分应用模式和后台限制 | 关闭其他VPN，恢复分应用设置，取消必要的后台限制后再测 |
| iOS | VPN配置批准状态、按需连接、蜂窝网络权限和分应用设置 | 关闭当前VPN配置，重新批准后再载入配置 |
| Linux | TUN权限、路由表、防火墙、systemd状态和本地监听端口 | 停止服务，恢复备份配置，再检查路由和防火墙变更 |
这些是排查优先级，不代表所有图形客户端的菜单名称完全相同。客户端内核、系统权限和TUN实现可能不同，具体以当前客户端设置页及对应版本文档为准。
验证结果、日志脱敏与撤销方法
完成一次修改后，至少做三项验证：客户端日志不再连续出现同类错误；本地代理端口处于监听状态；浏览器或目标应用能够完成实际访问。不要只依据“已连接”或“运行中”判断问题已经解决。
- 记录系统、客户端和sing-box内核版本。
- 记录失败阶段：订阅下载、配置启动、节点握手、DNS解析或网页访问。
- 保留一行代表性错误关键词和出现时间。
- 记录是否更换网络、关闭其他VPN或启用TUN。
- 记录每次只改动了哪一个字段，以及是否已恢复。
上传日志或截图前，隐藏订阅令牌、UUID、密码、私钥、认证头、完整节点链接和带凭据的URL。可以保留错误类型、时间、客户端版本和脱敏后的目标地址。
如果修改后问题扩大，先停止客户端，恢复备份配置，撤销系统代理或VPN权限变更，再逐项重新启用。版本和字段变化应以sing-box官方发布页及对应版本文档为准。
下一步：把问题缩小到一个变量
如果配置能启动但网页仍打不开，下一轮只选择一个变量：先固定节点和DNS，单独切换系统代理或TUN；如果节点握手失败，则固定客户端和网络，只核对当前协议的地址、端口与认证字段。每次修改后都执行日志验证、实际访问和回滚检查。
站内还可继续查看连接问题排查、设备配置指南和常见问题，但请先确认页面内容与当前客户端版本一致。
常见问题
sing-box check 命令无法执行怎么办？
先执行<code>sing-box --help</code>确认当前版本的命令和配置参数，再检查配置路径、文件权限与工作目录。不同版本的命令行参数可能不同，不要直接复制旧教程。
为什么不能用 curl -I 判断订阅是不是JSON？
因为<code>-I</code>只获取响应头，不会下载响应正文。应使用<code>curl -L -D headers -o body "订阅地址"</code>，再分别检查最终状态、响应头和实际正文。
订阅返回HTML页面，是不是一定失效？
不一定。可能是登录页、认证失败、重定向、访问策略或服务端错误页。它说明应优先检查订阅获取阶段，但不能单凭HTML断言配置来源失效。
sing-box 显示运行但浏览器打不开，先改DNS吗？
不建议。先确认本地入站端口、系统代理或TUN已经接管流量；只有日志或测试明确指向解析失败时，才继续检查DNS服务器、规则和默认DNS。
看到 connection refused，节点一定失效了吗？
不一定。也可能是端口填错、协议不匹配、访问策略或本地网络问题。先核对当前协议实际使用的地址和端口，再在不同时间或网络重复验证。
旧配置出现 geoip 或 geosite 字段怎么办？
先查看当前版本文档。官方迁移说明显示，这些字段已进入弃用或移除范围，通常应迁移到rule-set；不要为了消除报错直接添加不确定字段。
日志可以直接发给别人分析吗？
可以，但必须先隐藏订阅令牌、UUID、密码、私钥、认证头和完整节点链接。保留系统、版本、失败阶段、错误关键词和日志时间即可。