sing-box 连接不上怎么排查？从日志到恢复连接
简答：sing-box 连接不上时，最快路径是：先关闭 TUN 和复杂分流，查看第一条 error 或 fatal 日志，再用 sing-box check -c config.json 校验配置；随后测试本地监听端口、DNS 和节点端口，最后恢复 TUN、路由与系统代理。配置检查通过并不代表节点可用，成功判据是日志不再出现启动或握手错误，代理端口能被本机访问，浏览器或目标应用可以正常打开页面。本文是第三方使用指南，不代表任何客户端或服务提供方。
定义：sing-box 连接故障是指配置未能启动、节点握手失败、DNS 无法解析，或代理已运行但流量没有正确进入入站、路由和出站链路。
先做这 5 步：把故障分到正确层级
不要一开始同时改节点、DNS、TLS 和 TUN。按下面顺序做，哪一步失败，就先处理哪一层。
| 现象 | 先检查什么 | 判断标准 |
|---|---|---|
| 配置保存后无法启动 | JSON 格式、字段名称、版本兼容性 | sing-box check -c config.json 返回无错误；sing-box 配置使用 JSON 格式，官方也提供 check 和 format 命令。查看配置与命令说明 |
| 启动后所有节点超时 | 节点地址、远端端口、本地网络、防火墙 | 多个节点都失败，优先怀疑订阅、网络或配置整体问题；单个节点失败，再核对该节点参数。 |
| 出现 handshake failure 或 TLS 错误 | TLS、SNI、证书、传输方式、系统时间 | 配置中的 TLS 与服务端参数逐项一致，系统时间没有明显偏差。 |
| 日志显示运行但网页打不开 | DNS、路由、系统代理、TUN、应用是否使用代理 | 本地代理端口能访问，且流量确实进入 sing-box；仅启动成功不能证明网页流量已接管。 |
| 只有部分应用异常 | 应用代理支持、分流规则、UDP 或 IPv6 | 先用浏览器或命令行做单目标测试，再判断是否为应用自身不使用系统代理。 |
最短路径：关闭 TUN 和复杂规则，只保留一个可确认的出站，打开日志，执行配置检查，再测试本地 SOCKS 或 HTTP 入站。确认单节点能通后，一次只恢复一个变量。
第一层：看第一条关键日志，不要只看最后一行
日志配置支持 trace、debug、info、warn、error、fatal 和 panic 等级，也可以输出到文件。排障时优先记录第一条 error 或 fatal，以及它前后几行。官方日志字段说明（访问日期：2026-11-10）。
- JSON、unknown field、invalid character：先停止运行，检查 JSON 逗号、括号、引号和字段拼写，再运行
sing-box check -c config.json。 - permission denied：表示程序没有权限创建 TUN、监听端口或读取文件。先用普通入站测试；需要系统权限的 TUN 功能，按当前客户端的权限提示重新授权。
- address already in use：本地端口已被其他程序占用。更换入站端口，或关闭占用该端口的旧实例；不要同时启动多个相同配置。
- connection refused：目标地址主动拒绝连接，可能是远端端口未监听、端口写错或中间防火墙拒绝。它与 timeout 不同，不能仅靠修改 DNS 解决。
- timeout：在规定时间内没有建立连接。分别测试本地网络、远端 IP 或域名、远端端口，并对比其他节点。
- DNS resolution failed：域名解析阶段失败。检查 DNS 配置、DNS 规则和出站是否能访问 DNS；sing-box 的 DNS 配置包含 servers、rules、final 和 strategy 等字段。官方 DNS 配置说明
- no route：路由表没有为目标选择可用路径。检查 route 规则、默认出站、TUN 的 auto_route，以及是否与其他 VPN 或虚拟网卡冲突。
Windows、macOS 和 Linux 命令行客户端可先把前台日志保留下来；Android、iOS 或图形客户端则使用当前客户端提供的日志查看或导出功能。具体按钮名称可能随客户端版本变化，未核实的菜单路径不要照抄。
第二层：校验配置、订阅格式和节点参数
sing-box 使用 JSON 配置。订阅导入成功，不等于返回内容就是 sing-box 可运行配置：如果返回的是登录页、HTML 错误页、Clash YAML 或普通节点列表，客户端可能显示已保存，但核心启动或运行时会失败。
- 先把当前配置复制一份，保留原文件作为回滚版本。
- 在命令行进入配置所在目录，执行
sing-box check -c config.json；如果客户端使用多个配置文件，先确认实际加载的是哪一个。 - 检查 outbounds 是否存在可用的默认出站，route 是否将流量指向该出站，DNS 是否有可用的 final 或规则目标。
- 只保留一个节点做最小复现，暂时关闭复杂 rule-set、自动选节点、Fake-IP、TUN 和应用分流。
- 核对节点的地址、端口、UUID 或密码、协议、传输方式、TLS、SNI、证书校验和 ALPN 等字段；这些参数必须与提供方给出的配置一致。
配置检查只能证明结构和字段基本可被当前核心读取，不能证明远端节点在线、端口可达或认证成功。若最近升级过核心，优先对照当前官方配置文档和更新说明；没有资料证明的版本兼容性，写成“需核实”，不要直接判定配置已失效。官方文档还说明配置可用 JSON Schema 辅助编辑器校验。查看官方更新日志
第三层：测试本地端口、DNS 和远端端口
以下测试用于区分“本机没有监听”“DNS 失败”和“远端端口不可达”。测试地址请替换为你自己的入站端口、DNS 地址和节点域名，不要把订阅链接、UUID、密码或私钥粘贴到公开平台。
- Windows PowerShell：
Test-NetConnection 127.0.0.1 -Port 1080；测试远端端口可使用Test-NetConnection example.com -Port 443。 - macOS/Linux：
nc -vz 127.0.0.1 1080；测试远端端口可使用nc -vz example.com 443。 - DNS：Windows 使用
nslookup example.com；macOS/Linux 可使用dig example.com。若系统没有 dig，可用当前系统已有的 DNS 查询工具。 - HTTP 代理验证：若本地入站是 HTTP 代理，可使用
curl -x http://127.0.0.1:8080 https://example.com -I；若是 SOCKS 入站，使用curl --socks5-hostname 127.0.0.1:1080 https://example.com -I。
本地端口测试失败，先查入站监听、端口占用和防火墙；本地端口成功但远端端口测试失败，优先查节点地址、远端端口、网络出口或服务端状态；DNS 成功但握手失败，则转查 TLS、传输和认证。命令只能说明网络层是否有响应，不能证明协议、账号或分流配置正确。
第四层：TLS、DNS、路由和 TUN 的专项处理
TLS 或握手失败：核对 SNI 是否为服务端要求的域名，证书校验设置是否与配置一致，传输方式和端口是否匹配，并检查系统日期时间。不要为了“先连上”长期关闭证书校验；如果必须做临时对照测试，完成后立即恢复。
DNS 失败或网页打不开：先确认 sing-box 的 DNS servers、rules 和 final 是否有可用目标，再检查路由是否把 DNS 请求送入正确的 DNS 处理链。官方文档列出了 DNS 的默认超时、解析策略和缓存字段，字段名称应以当前文档为准。DNS 官方文档
TUN 已开启但系统断网：先关闭 TUN，改用本地 HTTP 或 SOCKS 入站验证节点；如果普通代理可用，再检查 TUN 的 auto_route、DNS 劫持、路由排除项、系统权限，以及其他 VPN、虚拟机网卡和安全软件冲突。官方 TUN 文档说明，auto_route 会将默认路由指向 TUN；Windows、Linux 和 macOS 的支持范围及字段行为也可能随版本变化。TUN 官方字段说明
部分应用不通：系统代理并不等于所有应用都会使用代理；官方客户端说明也指出，许多非 HTTP 客户端不会检查系统代理。此时用 TUN 或应用自身的代理设置处理，并单独核对 UDP、IPv6 和分流规则。官方客户端代理说明
按设备执行：Windows、macOS、Linux、Android 和 iOS
| 设备 | 建议顺序 | 回滚方式 |
|---|---|---|
| Windows | 导出日志；运行配置检查；测试本地端口；关闭 TUN 和其他 VPN；再恢复系统代理或 TUN。 | 关闭 sing-box，恢复原系统代理设置，使用备份配置。 |
| macOS | 先用普通代理验证；再检查系统扩展或 VPN 权限、DNS 和 TUN；确认没有其他网络扩展抢占路由。 | 关闭配置和系统扩展，恢复原网络代理与 DNS。 |
| Linux | 检查前台日志、监听端口、路由表和防火墙；使用 TUN 时重点核对 auto_route、auto_redirect 和默认网卡。 | 停止服务，删除本次新增的路由或防火墙规则，恢复原配置。 |
| Android | 检查 VPN 权限、电池限制、应用分流和 DNS；一次只启用一个 VPN 类应用。 | 断开 sing-box VPN，撤销 VPN 权限或切回系统网络。 |
| iOS | 检查 VPN 配置授权、应用分流、DNS 和当前配置是否仍在使用；先用单节点最小配置测试。 | 断开 VPN，删除或停用临时配置，重新加载备份配置。 |
官方图形客户端页面将 Android、Apple 平台、Windows 和 Linux 客户端分开列出；不同客户端的日志、权限和配置入口不能互相套用。官方图形客户端列表
排查完成后的成功判据与安全脱敏
完成处理后，至少满足以下条件：配置检查无错误；客户端启动后没有新的 fatal 或持续性 error；本地代理端口能建立连接；单节点通过 HTTP 或 SOCKS 测试；浏览器或目标应用可以访问；恢复 TUN 或分流后仍然正常。
如果需要提交日志，只保留时间、错误类型、系统、客户端类型、核心版本和复现步骤。删除订阅完整地址、UUID、密码、私钥、API 密钥、服务器地址中可识别的敏感部分。不要为了排障公开完整配置文件。
仍无法定位时，采用二分法：单节点与多节点、普通代理与 TUN、直连 DNS 与 sing-box DNS、关闭规则与启用规则分别测试，每次只改变一个变量。这样可以判断问题来自配置、节点、DNS、路由还是系统接管，而不是凭感觉反复换参数。
常见问题
sing-box check 通过了，为什么还是连接不上？
check 主要验证配置能否被当前核心读取，不会替你证明节点在线、远端端口可达、TLS 参数正确或应用流量已经进入 TUN。继续看握手日志，并分别测试本地端口、DNS 和远端端口。
所有节点都 timeout，应该先换节点吗？
不建议立即换。先确认订阅内容没有变成 HTML 或错误页，再检查本地网络、系统时间、DNS、默认出站和端口。只有单个节点失败时，才更适合优先核对该节点参数。
为什么浏览器能用，但某个应用仍然无法联网？
该应用可能不使用系统代理，或被分流规则、IPv6、UDP 或应用自身网络策略影响。先用 TUN 做对照，再查看该应用是否支持 HTTP 或 SOCKS 代理，并检查对应日志。
开启 TUN 后全部断网，怎样快速恢复？
先断开 TUN，恢复普通 HTTP 或 SOCKS 入站；确认节点可用后，再逐项检查 TUN 权限、auto_route、DNS 处理、路由排除项，以及其他 VPN 或虚拟网卡冲突。
可以把完整配置发给别人帮忙看吗？
不建议。应先删除订阅链接、UUID、密码、私钥、API 密钥和可识别的服务器地址，只保留字段结构、错误信息和脱敏后的最小配置。
常见问题
sing-box check 通过了，为什么还是连接不上？
配置检查通过不等于节点在线或流量已接管，还要继续检查握手、DNS、远端端口、路由和应用代理设置。
所有节点都 timeout，应该先换节点吗？
先检查订阅返回内容、本地网络、DNS、默认出站和端口；确认不是整体配置或网络问题后，再单独核对节点。
为什么浏览器能用，但某个应用仍然无法联网？
该应用可能不使用系统代理，也可能受分流、IPv6、UDP 或应用自身网络设置影响，应使用 TUN 或应用代理设置做对照。
开启 TUN 后全部断网，怎样快速恢复？
先断开 TUN，恢复普通 HTTP 或 SOCKS 入站并确认节点可用，再逐项检查权限、auto_route、DNS、路由排除项和其他 VPN 冲突。
可以把完整配置发给别人帮忙看吗？
不建议。先删除订阅地址、UUID、密码、私钥、API 密钥和可识别的服务器地址，只分享脱敏后的最小配置和日志。