sing-box 节点连接失败怎么办？按日志、DNS、端口逐层排查
简答：先不要反复更换节点：第一步查看最早出现的 ERROR 或 FATAL，第二步用 sing-box check -c config.json 校验配置，第三步区分本地端口、远端节点、DNS 和系统代理问题。单节点失败通常先核对参数；全部节点失败则优先检查配置、网络、权限或服务端状态。
定义：sing-box 节点连接失败，是指配置能够导入或程序能够启动，但代理出站在建立 TCP、TLS、UDP、DNS 或目标网站连接时失败。
先看这一张：一分钟判断故障在哪一层
本文是第三方使用指南，不代表任何客户端或节点服务商。排查时建议先保留原配置，复制一份测试配置，避免直接删除正在使用的文件。
| 现象或日志关键词 | 优先怀疑 | 先做什么 | 下一步 |
|---|---|---|---|
sing-box check 直接报错 | JSON、字段、版本或配置结构 | 备份后执行配置校验 | 按第一条错误修复，不要先换节点 |
connection refused | 端口未监听、地址或端口错误、服务端拒绝 | 核对服务器地址和端口 | 换网络复测；仍失败时核对节点来源 |
connection timeout | 网络不可达、端口被丢弃、路由或节点不可用 | 对同一节点换网络测试 | 判断是单节点、全部节点还是本地网络 |
handshake failure、TLS 错误 | SNI、证书、TLS、Reality 或传输参数 | 逐项对照节点参数 | 确认客户端核心支持该字段 |
DNS resolution failed | DNS 配置、域名解析或路由 | 单独测试域名解析 | 临时使用已知可用网络复测，完成后恢复设置 |
| 程序启动但网页打不开 | 系统代理、TUN/VPN 权限、路由或规则 | 确认应用流量是否进入 sing-box | 用单节点、直连规则和最小配置复现 |
官方文档说明 sing-box 使用 JSON 配置，并提供 sing-box check 校验命令；配置字段和可用功能会随安装的核心版本变化，具体以当前版本文档和本机命令帮助为准。查看 sing-box 配置文档
第一步：备份配置并检查配置文件
- 先备份。将当前配置复制为测试文件，例如
config-test.json。不要在未备份的情况下覆盖订阅配置、删除节点或清空配置目录。 - 确认文件路径。图形客户端通常允许在配置详情、编辑配置或打开配置目录中查看实际文件；Windows、macOS、Android 和 iOS 的界面可能不同，应以当前客户端显示为准。
- 运行校验命令。在 Windows PowerShell、macOS 终端或 Linux 终端中执行：
sing-box check -c config-test.json。该命令适用于已安装命令行核心且终端能够找到sing-box的环境。 - 预期结果。如果命令没有返回错误，说明配置格式和已识别字段通过了基础校验，但不等于节点一定可连接。若出现 unknown field、missing required field、invalid value 等信息，先修复最早出现的错误。
- 命令找不到时。如果出现“不是内部或外部命令”或类似提示，说明当前终端没有找到核心程序。改用客户端内置的配置检查功能，或在终端中进入核心程序所在目录后再执行；不要随意下载不明构建版本。
sing-box 官方还提供 JSON Schema，可用于编辑器补全和字段校验；生成的 Schema 应与本机安装的核心版本匹配。查看官方 JSON Schema 说明
第二步：核对节点参数，不要只看节点名称
节点能导入，只代表订阅或配置文件被读取，不代表连接参数正确。将失败节点与服务方提供的原始信息逐项对照，重点检查以下字段：
- 地址与端口：核对服务器域名或 IP、端口数字，以及是否误把本地端口填成远端端口。
- 协议与认证：确认出站类型、UUID、密码、用户信息、加密方式和传输模式一致。缺少或多余字段都可能导致握手失败。
- TLS 参数：核对是否启用 TLS、
server_name或 SNI、证书校验方式、ALPN 和传输层设置。官方 TLS 文档列出了客户端支持的常见字段，但不同核心版本与平台引擎可能存在差异。查看 sing-box TLS 字段 - Reality 或传输参数：如果节点依赖公钥、短 ID、传输路径、请求头或其他协议参数，必须完整复制，不能凭经验补写。
- 客户端分支：如果配置中出现图形客户端专用字段、实验字段或第三方扩展，先确认当前客户端是否支持。不能因为配置在某个客户端可用，就推断上游核心一定支持。
最小核对方法是只保留一个失败节点和一个明确的出站，暂时移除复杂规则、自动选择组和远程规则集。复现完成后再逐项恢复，这样才能判断问题来自节点本身还是配置组合。
第三步：按顺序测试本地端口、远端端口、DNS 和网页
不要把“延迟有返回”直接当成节点可用。连接测试至少要区分四层：本地代理端口是否监听、远端节点端口是否可达、域名能否解析、目标网页能否通过代理加载。
- 测试本地端口。启动 sing-box 后，在 Windows PowerShell 执行
Test-NetConnection 127.0.0.1 -Port 本地端口；在 macOS 或 Linux 执行nc -vz 127.0.0.1 本地端口。预期是端口显示可连接或 succeeded。若失败，先检查核心是否启动、入站端口是否冲突，以及图形客户端是否实际运行了该配置。 - 测试远端 TCP 端口。Windows 可执行
Test-NetConnection 节点域名 -Port 节点端口；macOS 或 Linux 可执行nc -vz 节点域名 节点端口。这只能说明 TCP 层是否有响应，不能证明认证、TLS 或代理转发成功。命令不通时，换一个网络复测；仍不通则核对地址、端口和节点状态。 - 测试 DNS。Windows 执行
nslookup 节点域名，macOS 或 Linux 执行dig 节点域名。如果域名无法解析，先排查本机 DNS、网络切换和 DNS 路由；不要在未确认原因时长期关闭系统安全设置。 - 测试网页加载。先用一个明确的单节点和单一目标测试，再观察日志是否出现出站连接、DNS 解析和返回结果。网页打不开但 DNS 正常，可能是规则、系统代理、TLS、目标网站或节点出口问题。
如果只使用 TUN 入站，必须确认系统已经授予 VPN 或网络扩展权限，并检查是否存在其他 VPN、代理软件或安全软件冲突。权限和界面入口会因 Windows、macOS、Android、iOS 以及客户端版本不同而变化，无法核实的路径应以当前客户端页面为准。
第四步：根据日志关键词分流处理
| 日志关键词 | 含义 | 处理顺序 |
|---|---|---|
timeout | 在限定时间内没有得到连接响应 | 换网络；核对地址和端口；比较一个节点与全部节点的结果 |
connection refused | 目标端明确拒绝连接 | 核对端口、协议和服务端状态；不要只重复刷新客户端 |
handshake failure | 建立加密或协议握手失败 | 核对 TLS、SNI、证书、Reality、传输和核心兼容性 |
DNS resolution failed | 域名没有成功解析 | 单独测试 DNS；检查 DNS 路由和网络环境 |
permission denied | 系统拒绝访问网络设备、端口或 TUN/VPN 能力 | 检查管理员权限、VPN 权限和其他软件占用 |
no route | 系统或 sing-box 没有找到可用路由 | 检查 TUN、路由规则、直连规则和默认出站 |
如果日志很多，优先看第一次出现的 ERROR 或 FATAL，而不是最后一行衍生错误。Linux 使用 systemd 管理服务时，官方文档给出了查看服务日志的命令：sudo journalctl -u sing-box --output cat -e；实时观察可使用 sudo journalctl -u sing-box --output cat -f。查看官方服务与日志命令
提交问题前应删除订阅链接、密码、私钥、UUID、完整服务器地址和其他敏感字段，只保留核心版本、系统、脱敏配置片段、最早错误及复现步骤。
第五步：四个平台的最短排查路径
- Windows：先关闭其他代理软件，确认系统代理是否指向 sing-box 的本地端口；再用 PowerShell 测试本地端口和远端端口。若使用 TUN，检查是否获得管理员或网络权限，测试结束后恢复原系统代理设置。
- macOS：确认网络扩展、VPN 权限和系统代理状态没有与其他工具冲突；用终端运行配置校验和 DNS 测试。若修改了系统代理，记录原值并在回滚时恢复。
- Android：确认当前配置已启用、VPN 权限仍然有效，并检查省电策略是否暂停后台核心。先用单节点测试，再判断是节点问题还是应用分流问题。不同客户端的配置目录和日志入口可能不同。
- iOS：确认 VPN 配置授权和当前配置状态正常；如果订阅更新成功但连接失败，优先检查节点字段与核心兼容性，不要把“订阅能下载”当成“节点可用”。客户端名称、配置入口和支持字段以当前应用页面为准。
四个平台都应遵循同一个顺序：保留原配置、复制测试、单节点复现、查看日志、恢复复杂规则。不要为了排障长期关闭 Private DNS、系统防火墙或安全软件；如需临时停用某项功能，应记录变更并在测试后立即恢复。
最小化复现与回滚方法
- 复制当前配置为测试配置，并记录客户端、核心版本、操作系统、网络类型和测试时间。
- 只保留一个节点、一个本地入站、一个默认出站，暂时移除自动选择组、复杂规则、远程规则集和非必要 DNS 分流。
- 执行
sing-box check -c config-test.json，确认配置先通过基础检查。 - 启动测试配置，依次测试本地端口、远端端口、DNS 和目标网页。
- 若测试配置成功，按“DNS、规则、自动选择组、TUN、其他节点”的顺序一次恢复一项；哪一项恢复后再次失败，基本就找到了故障范围。
- 若最小配置仍失败，换一个网络或另一个节点做对照。单个节点失败不等于全部节点故障；全部节点在不同网络都失败，才值得进一步核对服务端信息或公开状态。
- 测试结束后停止测试配置，恢复原配置文件、系统代理、VPN 权限和 DNS 设置。
如果订阅可以更新但节点全部无法连接，优先把问题拆成两部分：订阅下载链路是否正常，以及节点握手链路是否正常。前者成功只能证明订阅地址可访问，不能证明节点地址、端口、认证和 TLS 参数仍然可用。
什么时候可以判断需要联系节点提供方
满足以下条件后，再联系节点提供方更有效：配置校验通过；单节点测试仍失败；至少换过一个网络；已经区分本地端口、DNS 和远端端口；日志中出现明确的远端拒绝、超时或握手错误。反馈时提供脱敏后的核心版本、系统平台、节点协议类型、错误关键词、复现时间和是否全部节点受影响。
如果只有一个节点失败，先请求核对该节点的地址、端口和参数；如果全部节点失败但本地端口正常，提供脱敏日志并说明换网络后的结果；如果本地端口都没有监听，则应先解决客户端或核心启动问题，而不是直接要求更换节点。
常见问题
sing-box 节点连接失败，应该先换节点吗？
不建议一开始就换节点。先查看最早的 ERROR 或 FATAL，再运行 sing-box check -c config.json。若配置检查失败，换节点通常不能解决；若只有一个节点出现 timeout 或 refused，再针对该节点核对地址、端口和参数。
sing-box check 通过了，为什么节点还是连不上？
check 主要用于发现配置格式和可识别字段问题，通过不代表远端节点、TLS、认证、DNS 或目标网站一定可用。接下来应测试本地端口、远端端口、DNS 和网页加载，并结合日志分流。
订阅可以更新，但 sing-box 节点全部连接失败，问题在哪里？
订阅更新成功只说明订阅地址能够访问，不等于节点握手成功。请将订阅下载、配置启动、节点连接和网页加载分开测试；确认配置校验通过后，用单节点和另一网络复测。
connection refused 和 connection timeout 有什么区别？
refused 通常表示目标端明确拒绝连接，优先核对端口、协议和服务端监听；timeout 表示在限定时间内没有获得响应，优先检查网络可达性、路由、端口丢弃和节点是否可用。两者都不能仅凭一条日志断定整体服务状态。
能不能直接关闭 DNS、系统防火墙或 Private DNS 来排查？
不建议长期关闭。排查前先记录原设置，优先用 DNS 查询、换网络、最小配置和日志定位；如确需短时对照测试，应在测试后立即恢复，并确认问题是否确实由该设置引起。
提交 sing-box 日志时需要注意什么？
删除订阅链接、密码、私钥、UUID、完整服务器地址及其他敏感信息，只保留核心版本、系统、脱敏配置片段、最早错误和复现步骤。不要直接公开完整配置文件。