sing-box 连接失败怎么办？按日志、配置与网络分步排查
简答：先不要反复切换节点：先确认失败发生在哪个阶段，再运行配置检查并查看日志。若配置能启动，再按 timeout、connection refused、handshake failure、DNS error 分别检查端口、协议参数、DNS、TUN 与路由。每次只改一个条件，用同一目标重新验证。
定义：sing-box 连接失败，是指配置无法启动、节点无法完成连接，或代理已运行但目标流量没有正确经过代理。
先用三步速查：不要先换一堆节点
普通用户路径：先确认是导入失败、启动失败、节点失败，还是启动后无法访问；然后校验配置并查看日志；最后只修改一个变量重新测试。
进阶路径：如果你使用 TUN、DNS 规则或自建服务，再检查监听端口、系统防火墙、云安全组、路由回环、DNS detour 和协议参数。本文只讲客户端与连接排查，不包含服务端搭建教程。
| 看到的现象 | 优先检查 | 最小验证动作 |
|---|---|---|
| 订阅或配置导入失败 | 链接可访问性、返回格式、JSON 与 YAML 类型 | 保存为本地文件后检查文件类型和内容开头 |
| 启动即退出或报配置错误 | 字段名称、版本迁移、JSON 语法 | 运行 sing-box check |
| 配置能启动但节点超时 | 服务器地址、端口、TCP/UDP、TLS 或协议参数 | 查看日志中的 timeout、refused |
| 显示运行但网页打不开 | 代理端口、DNS、route、TUN 权限和分应用设置 | 先用本地代理端口测试，再启用 TUN |
官方配置文档说明 sing-box 使用 JSON 配置，并提供 sing-box check 检查命令；配置结构可参考官方配置文档。
最短可执行步骤：备份、校验、看日志、复测
- 备份原配置。复制配置文件或导出当前配置，先不要覆盖原文件。分享日志或配置前，隐藏订阅令牌、UUID、密码、私钥、服务器地址中的敏感信息。
- 确认实际版本。在终端运行
sing-box version，或在图形客户端的关于页面查看版本。不要直接把旧教程中的字段复制到新版本。 - 校验配置。在配置文件所在目录运行
sing-box check -c config.json；如果当前版本只接受简写命令，可按官方文档使用sing-box check并通过配置参数指定文件。 - 提高日志信息量。临时将日志级别改为
debug，重启并复现一次，然后只截取失败前后的相关行。官方日志配置支持trace、debug、info、warn、error和fatal等级别，见官方日志配置说明。 - 固定测试条件。使用同一个节点、同一个目标域名和同一种网络连接，只修改一个参数。成功后再恢复其他设置，避免无法判断究竟是哪一项生效。
若校验失败，先修配置，不要继续测试节点；若校验通过但启动失败，重点看日志中的字段名、权限、端口冲突和平台能力。
按日志关键词分流：先解决最靠前的一条错误
| 日志关键词或现象 | 常见含义 | 下一步 |
|---|---|---|
invalid character、unknown field | JSON 语法错误或字段与当前版本不兼容 | 检查逗号、括号、字段拼写，并对照版本迁移文档 |
timeout | 目标地址或端口在规定时间内没有完成连接 | 核对服务器地址、端口、网络切换情况和 TCP/UDP 类型 |
connection refused | 目标端口主动拒绝连接，或服务未监听 | 检查端口监听、防火墙、云安全组和服务端协议类型 |
handshake failure、TLS | 握手参数或证书相关设置不匹配 | 逐项核对 server name、TLS、Reality 或其他协议参数；不要只改一个无关字段 |
DNS error、解析失败 | 域名无法解析，或 DNS 请求没有按预期路由 | 暂时对比系统 DNS 与 sing-box DNS，检查 DNS server、规则和 detour |
| 节点成功但网页打不开 | 代理监听正常，目标流量未被正确接管 | 检查系统代理、route.final、TUN 权限、分应用规则和 DNS 劫持 |
注意：这些关键词只能作为分流线索，不等于已经确定根因。应结合同一时间段的完整日志和复测结果判断。
如果配置来自旧教程，优先查看官方迁移说明。官方文档记录了旧版 DNS 格式、部分旧字段和 TUN 字段的迁移或移除情况。
配置能启动但无法访问：DNS、route 与 TUN 逐项检查
先排除代理端口问题
- 确认配置中的 HTTP 或 SOCKS 入站端口没有被其他程序占用。
- 在客户端内启用系统代理，或手动让浏览器使用该本地代理端口。
- 先测试普通域名访问，再测试需要 DNS 解析的目标；不要一开始就启用复杂规则。
再检查 route
如果使用 TUN，route 需要避免流量回环。官方文档说明，TUN 启用 auto_route 时，应配合 route.auto_detect_interface、route.default_interface 或出站绑定网卡等方式避免回环；route 还会决定默认出站和 Android VPN 的处理方式，具体字段见官方 Route 配置。
最后检查 DNS
DNS 配置包括服务器、规则、默认服务器和解析策略。若只有部分域名打不开，先检查 DNS 规则是否把请求送到了不存在或不可达的服务器，再暂时减少规则数量复测。官方 DNS 文档列出了 servers、rules、final 和解析策略等结构，见官方 DNS 配置。
TUN 专项检查
- Windows：确认客户端获准创建虚拟网卡，并暂时关闭可能冲突的其他 VPN、虚拟网卡或网络过滤工具。
- macOS：确认系统网络扩展或 VPN 权限已允许，若升级客户端后配置消失，重新导入备份配置。
- Linux：确认运行权限、TUN 设备、路由表和防火墙规则；启用自动路由后同时检查默认网卡绑定。
- Android：确认 VPN 权限、始终开启的其他 VPN、分应用代理和省电限制；若系统 VPN 与 TUN 叠加，检查是否需要启用 Android VPN 覆盖选项。
官方 TUN 文档还说明了 dns_mode、auto_route、auto_redirect 和 strict_route 的作用。不要把 Linux 的设置直接套到 Android 或 Apple 客户端上，平台图形客户端可能有自己的权限和能力限制，详见官方 TUN 配置。
协议与服务端可达性：客户端确认后再查远端
如果配置校验通过、客户端也能启动，但所有节点都出现超时或拒绝连接，问题可能不在客户端配置本身。按以下顺序核对：
- 服务器域名是否能解析到预期地址，端口是否与配置一致。
- 服务端进程是否监听对应 TCP 或 UDP 端口。
- 系统防火墙和云安全组是否放行相同协议与端口。
- 客户端与服务端的 TLS、Reality、Hysteria2、TUIC 等关键参数是否成对匹配。
- 如果只有 UDP 类节点失败，对比同网络下的 TCP 节点；如果只有 TLS 类节点失败，重新核对 server name、证书或握手参数。
不要因为某个节点失败就马上判断服务不可用，也不要把服务端未监听、端口被拦截和协议参数错误混为一类。客户端日志只能证明它观察到的失败阶段；服务端监听和防火墙仍需在服务器侧核验。
修复后的验证与撤销方法
- 重新载入：保存配置后重启 sing-box 或重新载入配置，确认日志不再出现新的启动错误。
- 先测本地代理：使用同一个本地 HTTP 或 SOCKS 端口访问一个普通网页，确认客户端确实接收到了请求。
- 再测 TUN：关闭系统代理，仅启用 TUN，测试同一目标，判断问题是在本地代理、TUN 接管还是 DNS。
- 记录结果：记录版本、系统、网络类型、节点标签、修改字段和复测结果，方便回滚或提交问题。
- 撤销修改：恢复备份配置，关闭临时 debug 日志，撤销新增 DNS、route 和 TUN 选项，再重启确认系统网络恢复。
如果需要求助，建议只提供脱敏后的版本信息、错误关键词、失败阶段和最小配置片段；不要公开订阅链接、访问令牌、UUID、密码、私钥或完整服务器凭据。
常见问题
sing-box check 报错，是否说明节点失效？
不是。check 主要用于发现配置结构、语法或字段问题；它通过后，仍可能因端口、网络、协议参数或远端服务导致连接失败。
配置是 Clash YAML，可以直接导入 sing-box 吗？
不能默认认为可以。sing-box 官方配置结构使用 JSON；第三方订阅转换结果还可能涉及字段映射和版本兼容，导入后应先检查文件格式，再运行配置校验。
为什么显示已连接，但浏览器仍然打不开？
“已连接”可能只代表客户端进程或 TUN 已启动，不代表浏览器流量已经被正确路由。先测试本地代理端口，再检查系统代理、route、DNS、分应用规则和 TUN 权限。
看到 timeout，是否只要换节点？
不一定。先核对服务器地址、端口、网络类型和防火墙；如果多个节点同时超时，应优先检查本地网络、订阅内容或共同的协议参数。
升级版本后突然连接失败怎么办？
先记录实际版本并查看迁移文档，再检查旧字段是否已废弃或移除。不要直接把旧配置和新配置混合修改，最好用备份逐项迁移。
常见问题
sing-box check 报错，是否说明节点失效？
不是。它主要检查配置结构和字段，节点是否可用还要单独检查网络、端口和协议参数。
配置是 Clash YAML，可以直接导入 sing-box 吗？
不能默认认为可以。sing-box 官方配置使用 JSON，转换后仍需检查字段兼容性并运行配置校验。
为什么显示已连接，但浏览器仍然打不开？
客户端运行不等于流量已接管。先测本地代理端口，再检查系统代理、DNS、route、分应用规则和 TUN 权限。
看到 timeout，是否只要换节点？
不一定。先核对地址、端口、TCP/UDP 类型和防火墙；多个节点同时超时时，应优先查共同配置或本地网络。
升级版本后突然连接失败怎么办？
记录实际版本，查看官方迁移说明，检查旧字段是否被废弃或移除，并用备份配置逐项迁移。