sing-box 连接不上节点怎么办？按故障阶段排查
简答：先不要反复换节点：只保留一个节点并查看日志，按“订阅—配置—节点—DNS/TUN”顺序定位。配置能通过检查且仅单节点失败，通常应转向节点或服务状态；全部节点失败则优先检查订阅、端口、权限和路由。
定义：sing-box 节点连接失败，是指客户端无法完成配置加载、协议握手或向目标节点建立可用连接，和“已连接但网页打不开”不是同一阶段。
先试这一步：用现象判断故障范围
先关闭其他代理客户端，只在 sing-box 中保留一个节点，访问一个固定网址，并记录日志中的第一条错误。不要同时修改 DNS、TUN、端口和节点参数，否则无法判断是哪项变化产生了结果。
| 现象 | 优先检查 | 可判定的方向 |
|---|---|---|
| 订阅无法导入或更新 | 链接完整性、返回内容、权限和格式 | 还没有进入节点连接阶段 |
| 内核启动失败 | 配置语法、字段版本、路径和端口占用 | 先修配置，不要测速 |
| 只有一个节点超时 | 节点地址、端口、协议参数和节点状态 | 更像单节点或参数问题 |
| 全部节点超时或握手失败 | 订阅、系统时间、网络、端口和防火墙 | 更像公共配置或网络问题 |
| 显示运行但网页打不开 | 系统代理、TUN 权限、DNS 和路由规则 | 节点可能已连通，流量未正确接管 |
sing-box 使用 JSON 配置，并提供 配置结构与 check 命令说明。因此第一步应验证配置能否被当前内核读取，而不是直接判断节点失效。
第一阶段：确认版本与配置没有先出错
- 确认当前内核版本：在终端执行
sing-box version。如果是图形客户端，在关于、内核或版本信息页面查看实际运行的内核版本，不要只看客户端外壳版本。官方版本列表会持续变化，可通过 sing-box 发布记录核对变化。 - 检查配置：在配置文件所在目录执行
sing-box check -c config.json。如果配置依赖额外目录，可按实际情况补充-D 配置目录。出现invalid config、未知字段或字段类型错误时，先删除不属于当前版本的字段，或依据对应版本的迁移说明调整。 - 检查 JSON 编辑器提示：官方文档说明可使用 JSON Schema 校验配置；也可以执行
sing-box schema -o schema.json生成与当前二进制匹配的 Schema，再在编辑器中引用它。参考sing-box JSON Schema 文档。 - 确认端口没有冲突：如果报错含
address already in use或bind: permission denied，说明本地入站端口可能已被占用，或当前进程权限不足。Windows 可在 PowerShell 中执行Get-NetTCPConnection -LocalPort 端口号 -ErrorAction SilentlyContinue；macOS、Linux 可执行lsof -nP -iTCP:端口号 -sTCP:LISTEN。
如果配置检查通过、端口也能监听，再进入节点连接排查；如果检查不通过，继续更换节点不会解决内核启动问题。
第二阶段：按日志关键词定位节点失败原因
日志应在客户端的日志面板查看；命令行运行时，可在配置的 log.output 文件中查看。官方日志配置支持 trace、debug、info、warn、error 等级，并可指定输出文件，详见sing-box 日志配置。
| 日志关键词 | 通常代表 | 处理顺序 |
|---|---|---|
timeout | 连接在规定时间内没有完成 | 换一个节点、换网络测试，再核对地址和端口 |
connection refused | 目标端口主动拒绝连接 | 核对端口、协议和节点服务状态 |
TLS handshake | TLS 握手阶段失败 | 检查系统时间、SNI、证书相关参数和传输方式 |
DNS failed 或 no such host | 域名无法解析 | 先测试 DNS，再检查 DNS 服务器、规则和 TUN 接管 |
invalid config | 配置字段或格式不被当前内核接受 | 重新执行 sing-box check 并按当前文档修改 |
permission denied | 创建 TUN、监听端口或访问文件权限不足 | 以系统要求的权限运行，或改用图形客户端授权 |
如果日志只显示泛化的“连接失败”，将日志级别临时调为 debug，复现一次后恢复为 info。提交诊断信息时应隐藏订阅链接、密钥、UUID、密码和完整节点凭据。
第三阶段：区分单节点失败与全部节点失败
只有一个节点连接不上
- 复制同一配置中的另一个节点，保持客户端、网络和规则不变。
- 只替换节点，不同时修改 DNS、TUN 或系统代理。
- 检查该节点的域名、端口、传输方式、TLS 参数、认证信息是否与订阅内容一致。
- 如果其他节点可以连接，而该节点持续出现
timeout或connection refused，可暂时将其归类为单节点或节点参数问题；节点是否维护、过期或流量受限，需要向服务提供方核实。
全部节点都连接不上
- 重新获取订阅，确认返回内容不是登录页面、错误提示或空白内容。
- 确认系统时间和时区正确。TLS 握手对时间敏感，时间明显错误时先修正系统时钟。
- 关闭其他 VPN、代理、网络过滤软件和重复的 TUN 实例，避免多个程序争抢路由或端口。
- 使用手机热点或另一条网络做一次对照测试。若仅一条网络失败，重点检查该网络的 DNS、端口可达性或防火墙；若所有网络都失败，回到订阅、配置和节点状态检查。
这个过程的关键是“每次只改变一个条件”。不要把换节点、换网络、改 DNS 和切换 TUN 同时进行，否则无法形成可复现结论。
第四阶段：已显示连接，但网页仍打不开
sing-box 的客户端接管方式主要包括系统代理、防火墙重定向和虚拟接口。官方对三种方式的差异有说明：系统代理并不能覆盖所有应用，UDP、ICMP 或不读取系统代理的程序可能绕过它；TUN 则通过虚拟网络接口接管流量，详见sing-box 客户端代理方式说明。
- 检查系统代理端口：如果使用 HTTP 或 mixed 入站，确认系统代理填写的地址与端口和配置中的监听端口一致。常见错误是客户端监听了一个端口，系统代理却仍指向旧端口。
- 检查 TUN 权限：桌面端启用 TUN 后，如果系统没有授予 VPN、网络扩展或管理员权限，可能表现为界面显示运行但流量没有进入 TUN。先关闭 TUN，测试系统代理；如果系统代理正常，再单独处理 TUN 授权。
- 检查 DNS：如果 IP 地址可访问、域名打不开，重点看
DNS failed、no such host或 DNS 请求是否被错误规则接管。sing-box 的 DNS 由servers、rules和final等字段组成，可参考DNS 配置文档。 - 检查路由顺序：sing-box 规则按顺序匹配。TUN 场景不要只看“已启动”，还要确认流量是否命中了正确的出站。官方 TUN 示例将
sniff放在前面，再处理 DNS 劫持，并通过路由设置默认出站；具体字段以TUN 配置文档和Route 配置文档为准。
可先用一个普通网页和一个固定域名做最小测试，再逐步恢复规则集。若关闭规则后能访问，问题通常位于 DNS 规则、路由顺序、规则集下载或默认出站，而不一定是节点本身。
按系统执行最短排查路径
| 系统 | 先做什么 | 仍失败时看什么 |
|---|---|---|
| Windows | 确认 TUN 或系统代理权限，检查端口占用，并用 PowerShell 查看监听端口 | 日志中的 TLS、DNS、权限和路由错误；关闭其他网络接管程序后重测 |
| macOS | 确认网络扩展或 VPN 权限，检查系统代理端口是否与入站一致 | 图形客户端的服务日志；Apple 图形客户端可在 Settings → View Service Log 查看崩溃日志，官方说明见Apple 客户端特性文档 |
| Android | 确认 VPN 权限、后台运行和电池限制，先用单节点测试 | 检查 TUN 是否与其他 VPN 冲突，并对比 Wi-Fi 与移动网络 |
| iOS | 确认系统 VPN 权限和配置已启用，避免同时运行其他 VPN | 查看客户端日志，分别测试 Wi-Fi 与蜂窝网络 |
| Linux | 先执行配置检查；TUN、自动路由或防火墙重定向通常需要相应权限 | 查看终端输出、配置的日志文件，以及路由和防火墙规则是否重复 |
移动端没有统一的“日志目录”可供所有客户端使用，实际位置取决于图形客户端。桌面命令行运行时，优先使用配置中明确设置的日志输出文件，避免凭经验猜路径。
什么时候可以判断需要联系节点服务提供方
完成以下对照后，才适合把问题提交给服务提供方：配置检查通过；客户端和内核版本已记录；至少测试过两个节点；至少更换过一次网络；系统时间正确；日志能稳定复现同一错误；并且没有其他 TUN、VPN 或代理程序冲突。
- 提供操作系统、客户端名称、内核版本和发生时间。
- 说明是单节点失败还是全部节点失败，以及换网络后的结果。
- 提供脱敏后的第一条关键日志，例如
timeout、connection refused或TLS handshake。 - 不要发送完整订阅链接、密码、UUID、私钥、访问令牌或 Cookie。
如果服务方无法确认节点状态，本文只能将问题定位到“节点或服务侧待核实”，不能据此断言节点一定失效。
最后核对：2026-10-26
sing-box 的配置字段和图形客户端功能会随版本变化。本文不把某个版本号当作长期固定结论；排查时应以当前执行的 sing-box version、配置检查结果和官方文档为准。若版本升级后突然出现未知字段、TUN 行为变化或 DNS 异常，优先查看官方变更记录，再调整配置。
常见问题
sing-box 显示已启动，但所有节点都超时怎么办？
先确认配置检查通过，再关闭其他 VPN、代理和 TUN 实例；随后换一条网络测试，并查看日志是 timeout、TLS handshake 还是 DNS failed。全部节点、多个网络都失败时，再核对订阅状态和服务侧信息。
sing-box 连接不上节点，是不是订阅失效了？
不一定。订阅失效通常表现为无法更新、返回错误页面或更新后节点为空；如果订阅能正常导入但只有一个节点超时，更应先检查该节点地址、端口和协议参数。
为什么 sing-box 连接成功后还是打不开网页？
这通常不是节点握手问题，而是系统代理、TUN 权限、DNS 或路由规则没有正确接管流量。先用单个域名测试，再检查系统代理端口是否与入站监听端口一致。
配置文件提示 invalid config 怎么处理？
执行 sing-box check -c config.json，记录第一条字段错误，确认当前内核版本，再根据官方配置文档或变更记录修改。不要直接复制其他版本的配置，也不要一次修改多个字段。
什么时候可以判断是节点或服务商的问题？
当配置检查通过、至少两个节点对比过、换网络后仍只有特定节点失败，并且日志持续出现 timeout 或 connection refused 时，可以将问题归类为节点或服务侧待核实，但仍不应在未核验前断言服务一定故障。