sing-box 连接失败错误代码解决：从日志到修复
简答：先确认 sing-box 内核版本和失败阶段，再保存脱敏日志并运行 sing-box check -c 配置文件。connection refused 先查端口，timeout 查可达性，handshake 或 DNS 报错分别检查 TLS 参数与解析路径。
定义：sing-box 连接失败错误代码，是客户端或核心在配置加载、DNS 解析、建立 TCP/UDP 连接、TLS 握手、路由或 TUN 初始化阶段输出的诊断关键词，不一定代表同一个故障原因。
先做这一步：确认失败发生在哪个阶段
本文是第三方使用指南，与 sing-box 项目及其开发者无隶属关系。不要先反复更换节点，先记录客户端平台、内核版本、配置来源、启用的协议、是否开启 TUN，以及首次出现错误的完整日志行。sing-box 配置使用 JSON，官方文档提供了配置检查、格式化和合并命令；图形客户端通常也会在 Core 或类似区域显示当前内核版本。可先查看 sing-box 配置文件结构与命令 和 sing-box 图形客户端通用功能。
| 日志关键词或现象 | 所属阶段 | 先验证什么 | 常见处理方向 |
|---|---|---|---|
| 配置解析、unknown field、invalid | 启动前 | 配置文件格式、字段和内核版本 | 运行 check，删除过期字段或按迁移文档改写 |
| connection refused | 连接建立 | 目标端口是否监听、地址是否写错 | 核对服务器地址和端口，检查防火墙或安全组 |
| connection timeout、i/o timeout | 连接建立或读写 | 域名解析、TCP/UDP 可达性、网络切换 | 区分 DNS、端口不可达和协议传输不匹配 |
| handshake、certificate、Reality verification | TLS 或协议握手 | 时间、SNI、证书校验和 Reality 参数 | 逐项对照服务端资料，不要凭猜测修改密钥 |
| DNS failure、no such host | 域名解析 | 解析服务器、DNS 路由和域名拼写 | 先用系统 DNS 验证，再检查 sing-box DNS 配置 |
| Initialize TUN device failed、permission denied | TUN 初始化 | 权限、虚拟网卡冲突和其他 VPN | 关闭冲突网络工具，授予权限或暂时改用系统代理 |
表中的“常见处理方向”是排查顺序，不是对具体日志的确定诊断；同一个 timeout 也可能来自 DNS、端口、TLS 或远端服务端未响应。
配置加载失败：先用 check，再看版本迁移
把实际配置文件复制为备份，例如 config.json.bak，然后在 sing-box 核心所在目录运行：
sing-box check -c config.json其中 config.json 要替换为你的真实配置路径。这个命令要求已安装可执行的 sing-box 核心，并且当前终端能够调用它；如果系统提示找不到命令，请在客户端的核心目录执行，或使用客户端提供的“检查配置”功能。正常标准是命令返回成功且没有 error、invalid 或 unknown field；若有报错，先修配置，不要进入节点测速。
如果配置能通过 check 但启动后仍失败，继续核对核心版本。官方迁移文档显示，sing-box 1.15.0 起 TUN 使用新的 TCP/IP 栈，旧的 stack 选项已标记为弃用；官方版本发布页同时列出稳定版和预发布版，版本号应以你实际安装的客户端为准。可查看 sing-box 迁移说明 与 sing-box 官方发布页。不要把别人的配置字段直接复制到当前版本，尤其是 TUN、DNS、rule-set 和 HTTP 客户端相关字段。
需要生成与当前核心匹配的 JSON Schema 时，可使用：
sing-box schema -o schema.json该命令需要支持 schema 子命令的核心版本；生成后可让兼容编辑器引用本地 schema.json。官方文档说明，生成的 Schema 会反映当前构建包含的功能，适合发现字段拼写或结构问题，但不能证明远端节点参数正确。参考 sing-box JSON Schema 文档。
connection refused、timeout 和 i/o timeout 怎么分
connection refused：通常表示已经到达某个地址，但目标端口拒绝连接，或目标主机主动返回拒绝。先核对地址、端口和传输类型；如果你管理服务端，检查对应端口是否监听，再检查服务器防火墙和云安全组。若只使用远端订阅，无法登录服务端时，应向提供配置的一方核对节点是否仍在服务，不要把“拒绝连接”直接判断为本地 DNS 故障。
connection timeout：更适合先查“能否到达目标”。在 Windows PowerShell 中执行以下命令，示例域名和端口必须替换为配置中的真实地址：
Test-NetConnection example.com -Port 443example.com 和 443 仅为示例，分别替换为节点域名和端口。正常标准是 TcpTestSucceeded : True；如果为 False，优先检查网络、地址、端口、防火墙或安全组。该命令只验证 TCP，不能证明 TLS、Reality、Hysteria2 或 TUIC 参数正确。
在 macOS 或 Linux 可使用：
nc -vz example.com 443示例域名和端口同样需要替换。看到 succeeded 或 open，说明 TCP 端口层面有响应；看到 timed out 或 failed，则继续查可达性。若系统没有 nc，请先安装系统提供的 netcat 工具，或使用客户端内置连接测试。
i/o timeout：表示连接建立后的读写阶段没有在规定时间内完成，可能与链路丢包、UDP 不通、TLS 握手参数不匹配、远端响应慢或协议类型不一致有关。先比较同一节点在普通系统网络和 TUN 模式下的结果；如果关闭 TUN 后可用，重点转向路由、DNS 劫持、虚拟网卡和权限，而不是立即修改节点密码。
DNS、网页打不开与分流错误：先区分“能连节点”和“能访问目标”
节点测速成功，只能说明某个测试请求完成，不等于所有域名都能打开。若日志出现 no such host、DNS timeout 或网页提示无法解析，先检查域名拼写，再分别验证系统解析和 sing-box 的 DNS 路径。命令中的 example.com 要替换为实际打不开的域名：
nslookup example.com正常标准是返回至少一个地址且没有超时；如果系统也无法解析，先修复本地网络或 DNS。如果系统能解析但 sing-box 代理下失败，检查配置中的 DNS server、DNS route、域名解析器和规则集是否把 DNS 请求送入错误的 outbound。官方配置结构将 DNS、route 和 outbounds 分开定义，不能只改系统 DNS 就假设 sing-box 内部解析路径已经改变，详见 sing-box 配置文档。
若“IP 地址能访问、域名打不开”，优先检查 DNS 和 TLS 的 SNI；若“国内站点能打开、特定域名打不开”，检查规则是否误走 direct、DNS 是否被错误分流，以及远端协议是否允许该目标。不要把分流结果当成节点失效，先在日志中确认该域名匹配到的规则和 outbound。
官方 TUN 文档说明，dns_mode 自 sing-box 1.14.0 起用于控制 TUN 接口如何处理 DNS，disabled、native 和 hijack 的行为不同；当 auto_route 开启时，hijack 是默认模式。修改前先确认核心版本和平台，否则不要照搬其他版本的字段。参考 sing-box TUN 入站与 DNS 模式。
TLS handshake、certificate 与 Reality verification failed
这类错误发生在 TCP 或 UDP 通道之后，重点不是继续测试 DNS，而是逐项核对 TLS 参数。先确认系统日期和时区正确，再对照配置提供方给出的 server、server_name、端口、UUID、密码、public key、short_id、transport 和 flow。任何一项拼写、大小写或格式不一致，都可能让握手失败；无法核实的节点参数应标记为“未核实”，不要凭网上示例补全。
- certificate：检查 server_name 是否与证书校验要求一致；不要在不了解风险时关闭证书验证。
- Reality verification failed：重新核对 public key、short_id、server_name 和服务端协议版本，确认导入过程没有截断字符。
- handshake timeout：先确认端口可达，再检查传输类型、TLS 版本和网络是否拦截 UDP；官方配置中的 TLS 字段和版本行为要以当前文档为准。
- 能建立连接但网页立即断开：检查路由规则、传输层和目标协议是否匹配，不要只看节点列表中的“可用”。
日志级别可以临时提高到 debug 或 trace。官方日志文档列出了 trace、debug、info、warn、error、fatal 和 panic 等级别；排查完成后建议恢复为 info，避免长期记录过多敏感连接信息。参考 sing-box 日志配置。
TUN 初始化失败：权限、虚拟网卡和系统代理冲突
如果错误包含 Initialize TUN device failed、permission denied、interface already exists 或类似提示，先关闭其他 VPN、虚拟网卡工具和可能占用系统代理的客户端，再完全退出 sing-box 后重新启动。Windows 需要确认客户端具有创建 TUN 或虚拟网卡所需的权限；macOS、Linux 和 Android 的授权路径不同，应按客户端界面提示操作。官方桌面客户端文档明确将 TUN 透明代理列为平台功能，并列出 Windows 10 及以上和 Linux 的支持范围，参考 sing-box Desktop 官方文档。
- 先关闭 TUN，只保留系统代理或 SOCKS/HTTP 入站，确认节点本身能否连接。
- 如果普通代理可用，再重新开启 TUN，检查是否出现权限、路由或虚拟网卡错误。
- 若只在 TUN 下失败，检查
auto_route、DNS 模式、路由冲突和其他 VPN 是否仍在运行。 - 若关闭其他 VPN 后恢复，说明存在资源或路由竞争；逐个重新启用工具，找出冲突项。
不要把 TUN 初始化失败与远端节点失效混为一谈：前者发生在本机建立虚拟网络接口阶段，甚至可能尚未发出节点连接请求。
协议不兼容、订阅错误与敏感日志处理
如果日志出现 cipher not supported、unknown outbound、格式不识别或订阅导入失败，先判断问题发生在“订阅下载”“配置解析”还是“节点运行”。HTTP 状态码、认证失败和 JSON 解析错误属于下载或内容阶段；配置能保存但启动失败，多半要看核心版本与字段；启动成功但某个节点失败，则继续查协议参数和网络可达性。
协议兼容不能只看名称。VLESS、Trojan、Hysteria2、TUIC、WireGuard 等出站需要不同的地址、认证、TLS、传输或 UDP 条件；一个客户端能导入配置，不代表当前系统网络支持其中所有传输。若使用的是旧配置，先按官方迁移文档核对已弃用字段；不要把第三方页面中的版本结论直接套到当前核心。
提交日志前必须删除订阅 URL、UUID、密码、私钥、Reality 私钥、API secret、内网地址和可识别的用户名。保留错误关键词、时间、客户端平台、核心版本、协议类型和已脱敏的配置结构即可。这样既能提高排查效率，也能避免把可直接使用的凭据公开。
| 检查项 | 正常标准 | 未通过时下一步 |
|---|---|---|
| 配置检查 | sing-box check 无结构或字段错误 | 按当前版本修字段，不先测节点 |
| TCP 端口 | Test-NetConnection 或 nc 显示可建立连接 | 查地址、端口、防火墙和安全组 |
| DNS | 目标域名能解析且无超时 | 查 DNS 路径、规则和域名拼写 |
| TLS/协议 | 握手完成且日志不再出现验证错误 | 逐字核对 server_name、密钥和传输 |
| TUN | 虚拟网卡创建成功，系统代理或路由生效 | 查权限、冲突 VPN、auto_route 和 DNS 模式 |
还无法解决时，按这个顺序提交信息
如果仍然连接失败，按以下顺序整理：1）平台和客户端名称；2）sing-box 核心版本；3）失败发生在启动、解析、连接、握手还是访问网页；4）完整错误关键词和时间点；5）是否只在 TUN、移动网络或 Wi-Fi 下出现；6）脱敏后的相关配置结构；7）已执行命令及输出。不要只写“连不上”，也不要直接公开订阅链接和密钥。
若普通代理可用而 TUN 不可用，优先看本地权限与路由；若所有模式都出现 refused，优先核对远端地址和端口；若只有特定域名失败，优先查 DNS、规则和 TLS SNI；若升级后立刻出现 unknown field，优先查看迁移说明。这样能把问题从“节点好不好用”缩小到可验证的网络阶段。
常见问题
sing-box 出现 connection refused，是节点一定失效了吗？
不一定。它更适合先按端口拒绝处理：核对地址和端口，检查 TCP 是否可达；如果你能管理服务端，再确认端口监听、防火墙和云安全组。只有在这些检查都正常且仍被拒绝时，才把远端服务状态列为待核实。
sing-box check 通过了，为什么启动后仍然连接失败？
check 主要验证配置结构和字段，不会证明远端地址、TLS 参数、DNS、端口或协议传输可用。通过后应继续检查日志阶段，再分别验证 DNS、TCP/UDP 可达性、TLS 参数和 TUN 状态。
能测速但网页打不开，应该先改 DNS 吗？
不应直接改 DNS。先确认打不开的是所有域名还是特定域名，再检查规则匹配、DNS 路径、TLS SNI 和实际 outbound。测速成功只说明测试请求完成，不能证明分流和目标网页访问都正常。
TUN 初始化失败和节点连接失败有什么区别？
TUN 初始化失败发生在本机创建虚拟网络接口阶段，常见排查方向是权限、虚拟网卡冲突和其他 VPN；节点连接失败则通常已经进入 DNS、端口、TLS 或协议阶段。先关闭 TUN 验证普通代理，有助于区分两类问题。
提交 sing-box 日志时哪些内容必须隐藏？
至少隐藏订阅 URL、UUID、密码、私钥、Reality 私钥、API secret、内网地址和用户名。可以保留错误关键词、时间、平台、核心版本、协议类型以及脱敏后的配置结构。