sing-box 连接失败怎么排查
简答：sing-box 连接失败建议按“配置校验→日志定位→出站参数→DNS→路由与 TUN→版本兼容性”的顺序排查：先执行 sing-box check，确认配置能启动；再将日志级别临时调整为 debug，依据错误信息判断是节点参数、域名解析、路由循环、权限还是版本字段问题。
定义：sing-box 连接失败，是指配置文件无法启动、客户端无法建立出站连接，或 TUN/系统流量未能通过 sing-box 正常转发。
一、先确认是哪一种连接失败
不要一看到“连接失败”就直接更换节点。sing-box 的问题通常分为三类：配置加载失败、出站连接失败、系统流量没有进入或没有经过正确路由。三类问题的处理方法不同。
| 表现 | 优先检查 | 常见处理方向 |
|---|---|---|
| 客户端启动即报错或配置无法加载 | JSON 格式、字段名、版本兼容性 | 运行 sing-box check，按报错行修改 |
| 客户端已启动，但节点全部连接失败 | 出站类型、服务器地址、端口、认证和 TLS | 核对订阅或配置中的出站字段，不要混用其他客户端字段 |
| 节点显示可用，但打开网页失败 | DNS、路由规则、默认出站 | 检查 dns、route.final 和规则顺序 |
| 开启 TUN 后断网或出现连接循环 | TUN 路由、网卡绑定、系统权限 | 检查 auto_route、auto_detect_interface 或 default_interface |
官方配置结构中，dns、inbounds、outbounds 和 route 都是相互独立但会共同影响连接的主要模块，可先从对应模块排查。参考 sing-box 配置说明。
二、第一步：检查配置文件能否通过校验
- 备份当前配置文件，避免修改后无法恢复。
- 在终端或命令提示符中进入 sing-box 可执行文件所在目录，执行
sing-box check。 - 如果使用了配置目录或多个配置文件，确认命令实际读取的是当前正在运行的那一份配置。
- 按照报错顺序逐项修复，不要一次性删除大量字段；修复后重新执行检查。
官方中文文档列出了 sing-box check，并说明配置文件使用 JSON 格式。若只是排版混乱，也可以使用官方提供的 sing-box format 命令整理配置。参考 sing-box 配置检查与格式化说明。
重点核对以下内容：
- JSON 的逗号、括号和引号是否完整。
outbounds是否存在，且每个出站都有正确的type和tag。- 路由规则引用的出站标签，是否真的存在于
outbounds。 - DNS 规则引用的服务器标签，是否真的存在于
dns.servers。 - 配置是否使用了当前版本已废弃或已迁移的字段。
三、第二步：打开日志，判断失败发生在哪里
配置能够启动但无法连接时，日志比反复点击“重连”更有用。可以在排查期间临时提高日志级别：
{"log":{"level":"debug","timestamp":true}}
官方日志配置支持 trace、debug、info、warn、error、fatal 和 panic 等级别，也可以通过 output 将日志写入文件。参考 sing-box Log 配置。
| 日志现象 | 优先检查 |
|---|---|
| 配置解析、字段未知或字段类型错误 | 配置版本、字段拼写、JSON 类型 |
| 解析服务器域名失败 | DNS 服务器、DNS 规则、域名解析链路 |
| 连接超时或拒绝 | 服务器地址、端口、节点是否仍可用、网络是否可达 |
| TLS 握手失败或证书错误 | TLS 参数、服务器名称、证书校验及系统时间 |
| 路由循环、连接重复回到 TUN | auto_detect_interface、default_interface 和 TUN 路由 |
| 权限不足、无法创建 TUN | 系统权限、客户端授权、内核或平台支持情况 |
排查完成后可以把日志级别恢复为 info，避免长期输出过多调试信息。不要在公开反馈中直接贴出包含密码、密钥、订阅地址或完整认证信息的日志。
四、第三步：核对出站配置与节点参数
如果日志显示连接目标不可达，先核对出站本身，而不是先改 DNS。出站配置至少要确认服务器地址、端口、协议类型以及协议所需的认证或 TLS 参数。字段名必须以当前 sing-box 文档和配置提供方给出的格式为准。
- 确认
outbounds中存在实际使用的出站。 - 确认路由规则中的
outbound标签与出站的tag完全一致，大小写也不能随意修改。 - 确认服务器地址没有多余空格、协议前缀或复制时混入的不可见字符。
- 确认端口是数字，用户名、密码、UUID、密钥等认证字段没有被截断。
- 如果服务器地址使用域名，继续检查该域名是否需要通过
domain_resolver解析。
官方 Dial Fields 文档说明，出站或端点使用域名时，可以通过 domain_resolver 指定解析所用的 DNS 服务器；如果 DNS 服务器本身使用域名，也需要确保其解析链路已经配置。参考 sing-box Dial Fields。
五、第四步：排查 DNS 导致的“假连接失败”
有些情况并不是节点不能连接，而是域名无法解析，表现为网页打不开、应用一直转圈或日志中出现解析超时。此时检查 dns.servers、dns.rules 和 dns.final。
- 确认
dns.servers中至少有可用的 DNS 服务器，并且每个服务器的tag唯一。 - 确认
dns.final指向的标签存在；如果为空，官方文档说明会使用列表中的第一个 DNS 服务器。 - 检查 DNS 规则中的
server是否引用了存在的服务器标签。 - 如果只有部分域名失败，检查规则顺序以及是否把域名错误地分配给了不可达的 DNS 服务器。
- 如果 DNS 服务器填写的是域名，检查该 DNS 服务器的
domain_resolver。
sing-box 的 DNS 配置包括服务器、规则、默认服务器和解析策略等字段；DNS 规则的 route 动作会把查询发送到指定的 DNS 服务器。参考 DNS 配置 和 DNS Rule Action。
六、第五步：检查 route 与 TUN，避免路由循环
开启 TUN 后出现断网、所有连接超时或 sing-box 进程不断重连，常见方向是路由循环或系统流量没有正确进入 TUN。先暂时关闭 TUN，使用普通入站或客户端提供的普通模式测试：如果普通模式可用而 TUN 不可用，问题范围通常集中在 TUN、系统权限和路由设置。
- 确认 TUN 入站启用了与当前平台匹配的配置，尤其是地址和路由地址。
- 使用 TUN 自动路由时，检查
auto_route是否与预期一致。 - 检查
route.auto_detect_interface或route.default_interface，避免出站连接再次被送回 TUN。 - 如果设备存在多个网卡、虚拟网卡、VPN 或容器网络，逐个停用非必要网络组件后测试。
- 在 Linux 上，如果使用透明路由，核对系统防火墙、nftables 或相关转发规则是否与 TUN 配置冲突。
- 在 Android、Windows、macOS 等平台，确认客户端已经获得创建 VPN/TUN 所需的系统授权。
官方 TUN 文档明确说明，启用 auto_route 时应设置 route.auto_detect_interface、route.default_interface 或出站的 bind_interface 之一来避免回环；route 文档也说明 auto_detect_interface 用于将出站连接绑定到默认网卡。参考 TUN 配置 和 Route 配置。
七、第六步：检查版本变化与旧配置字段
如果配置以前能用，升级 sing-box 或更换客户端后突然失败，应检查版本迁移说明。不要只复制旧教程中的字段，因为官方迁移文档会记录字段废弃、重命名、迁移和删除情况。
- 检查配置中是否仍使用已标记为 deprecated 的字段。
- 核对 TUN 地址字段是否符合当前版本的
address、route_address和相关字段格式。 - 核对 DNS 规则是否混用了新旧规则语法。
- 如果是 Apple 平台客户端升级，确认配置和应用数据是否需要重新导入；具体以客户端说明为准。
官方 Migration 页面记录了不同版本的配置迁移事项，例如 TUN 地址字段合并、部分 DNS 规则变化以及旧字段替代方式。参考 sing-box Migration。无法确认某个字段是否仍受支持时，应以当前版本官方文档为准，不要根据旧截图判断。
八、推荐的最短排查流程
- 停用 TUN：先判断普通模式能否建立出站连接。
- 校验配置：执行
sing-box check，先解决所有配置错误。 - 开启 debug：查看失败发生在解析、握手、认证还是路由阶段。
- 核对出站：检查
type、tag、服务器、端口和认证字段。 - 单独检查 DNS：确认 DNS 服务器标签、规则和默认服务器均有效。
- 恢复 TUN：确认权限、自动路由和默认网卡设置，防止连接回环。
- 检查版本：对照 Migration 文档处理废弃字段和新旧语法。
每次只改一个因素，并在修改后重新测试。这样可以保留因果关系，避免把 DNS、路由和节点参数同时改动后仍无法判断真正原因。
常见问题
sing-box check 通过了，为什么还是连接失败？
sing-box check 主要用于确认配置能够被解析和检查，并不等于服务器一定可达、认证一定正确或 TUN 一定有权限。下一步应查看 debug 日志，分别检查出站连接、DNS 和系统路由。
节点能连接，但网页打不开，应该先改 DNS 吗？
不一定。先看日志判断是域名解析失败、路由规则没有匹配，还是默认出站为空或指向错误标签。只有确认问题发生在解析阶段时，才优先调整 DNS。
开启 TUN 后所有网络都断了怎么办？
先关闭 TUN，确认普通模式是否正常；然后检查系统授权、auto_route、auto_detect_interface 或 default_interface。如果设备同时运行其他 VPN、虚拟网卡或容器网络，也要排除路由冲突。
旧配置升级后报未知字段怎么办？
不要直接把未知字段删除后继续运行。先对照当前版本的官方 Migration 和配置文档，确认字段是重命名、迁移还是已经移除，再使用对应的新字段重写配置。
日志中出现服务器域名解析失败，应该检查哪里？
检查 DNS 服务器是否可用、DNS 规则中的 server 标签是否存在，以及出站或 DNS 服务器使用域名时是否设置了合适的 domain_resolver。
常见问题
sing-box check 通过了，为什么还是连接失败？
配置检查通过只代表文件能够被解析，不代表服务器可达、认证正确或 TUN 权限正常。请继续查看 debug 日志，并分别检查出站、DNS 和路由。
节点能连接但网页打不开，应该先改 DNS 吗？
先根据日志判断是 DNS 解析失败、路由规则不匹配还是默认出站错误。只有确认失败发生在解析阶段时，才优先检查 DNS。
开启 TUN 后所有网络都断了怎么办？
先关闭 TUN 测试普通模式，再检查系统授权、auto_route、auto_detect_interface 或 default_interface，并排除其他 VPN、虚拟网卡和容器网络的路由冲突。
旧配置升级后出现未知字段怎么办？
对照当前版本官方 Migration 和配置文档，确认字段是重命名、迁移还是移除，再按新语法重写，不要只凭旧教程删除字段。