背景：报错不是结论，只是线索
sing-box 是一个开源的通用代理平台，服务器端和客户端共用同一份 JSON 配置：服务器端决定接受什么样的连接，客户端决定每条流量走哪个出站（走哪个节点、直连还是拦截）。它连不上时，很多人第一反应是换节点、换协议、重装一通，最后问题还在原地——因为配置写错、端口被占、密钥对不上、证书或时间不对、DNS 与路由走错路，日志措辞各不相同，修法也完全不同。本文先给对照表，再讲定位步骤。前置知识：一份能跑起来的配置、出站名字（tag）；规则顺序与 DNS 排错见顺序篇与 DNS 篇。
动手前三步：先定位，再改配置
第一步：备份再改，改完先校验。 复制一份当前配置再动手，改完跑校验命令，语法通过再重启：
cp config.json config.json.bak
sing-box check -c config.json校验只保证格式和字段合法，不保证密钥、端口、路由语义正确，校验通过仍连不上很正常，这时才轮到日志。
第二步：临时开 debug，复现一次故障。 配置里的 log 段控制详细程度，从简到繁依次是 error、warn、info、debug、trace。日常用 info 或 warn 就够，排错时才临时开到 debug：
{ "log": { "level": "debug", "timestamp": true } }服务器端用 systemd 托管时看 journalctl -u sing-box，客户端看日志面板或控制台输出。复现一次故障，记下报错的时间点和完整的一行，只截半行去求助等于没给信息。
第三步：一次只换一个变量做对照。 换节点、改回直连、切全局模式、换设备，每次只动一处。换节点就好，问题在原来那条线路或服务端；所有节点都不行，问题更可能在本地配置、DNS 或系统代理上。查出根因后把级别改回 info。
五类报错对照表
| 报错关键词 | 大致含义 | 先查什么 |
|---|---|---|
| reality verification failed | Reality 认证没通过 | 公钥、short ID、SNI 是否与服务端一致 |
| parse / unknown field / duplicate tag | 配置写错或字段不被当前版本接受 | 报错指出的字段名、重复的 tag |
| listen / address already in use | 端口已被占用或无权监听 | 该端口被谁占了、是否重复启动 |
| certificate / handshake / TLS | 证书、握手或时间校验失败 | 系统时间、证书链、TLS 设置 |
| timeout / EOF / DNS | 连接超时、对方断开或解析失败 | 服务端状态、DNS 与路由去向 |
第一类：reality verification failed，认证没通过
这是 VLESS + Reality 最常见的报错。认证要素必须两端完全一致：客户端公钥要等于服务端私钥算出的公钥，short ID 要与服务端设置的短 ID 对上，SNI（握手时伪装的域名）也要与服务端设置的握手域名一致，任何一项抄错一位都会报这句。先核对三项是不是从服务端原样复制的、有没有多出空格或换行，再确认服务端改完配置真的重启生效了。不要为了“先连上再说”而关掉 TLS 校验，那只是掩盖了错配的根因。
版本搭配也值得留意：2026 年 10 月 27 日的一份公开 Issue 报告，内嵌 sing-box 1.14.3 与 1.14.4 的面板在对接 Xray-core v26.9.8 及更新版本时，VLESS Reality 出站会报这句，而同一服务端用 Xray-core 客户端可以连通；截至发稿，该 Issue 仍为开放状态，没有已确认的修复版本。“升级之后突然连不上”时，先用升级前的组合做一次对照，别急着认定线路问题。
第二类：配置解析失败，字段或 tag 有问题
报错里出现 parse、unknown field 或 duplicate tag，服务往往根本没跑起来。unknown field 通常是旧版本字段写进了新版本，或字段放错了层级，对照官方文档确认归属再改，不要直接删掉报错字段，删字段可能改变行为。duplicate tag 是两个出站或规则重名，改名并同步改掉所有引用即可。
第三类：端口监听失败，服务没起来
listen 失败或 address already in use 的意思是：想监听的端口已被别的进程占了，或者 sing-box 自己被重复启动了两次。先确认服务是不是已经在跑，再看占用端口的是不是上一次没退干净的旧进程，停掉重复的再启动，不要一上来就换端口。服务器端还要注意防火墙与安全组：本地监听成功不等于公网端口放行，本地能连、远程连不上时，先查端口放行。
第四类：证书与握手失败，先看时间
证书类报错常伴随 certificate 或握手失败的字样。最容易被忽略的原因是系统时间偏差过大：证书有有效期，时间差得太多，校验就会失败。先对时，再查证书链是否完整、证书域名与访问域名是否一致。刚升级过也要留意发布说明里的证书集合变化，例如 2026 年 10 月 24 日发布的 1.14.4 就涉及此项，升级后证书报错突然出现时，先用升级前的版本做对照。
第五类：超时、EOF 与 DNS，区分“服务端挂了”还是“路走错了”
timeout 是等不到回应，EOF 是对方提前断开，DNS 报错是域名没解析出来，三者都表现为“打不开”，最容易误判。看日志里这次连接最终走了哪个出站、目标域名解析到了哪个 IP：连接根本没发到服务端或解析结果异常，先按 DNS 分流的思路查；连接发到了服务端却超时或被断开，再查服务端状态、端口放行和线路本身；只有个别网站打不开、其余正常，优先怀疑规则与 DNS。出站分组的读者可对照出站分组实战，把故障节点固定下来单独测一次。
收尾清单
修好之后做三件事：把日志级别改回 info；删掉排错时临时加的绕过校验、全局模式等临时改动；把最终能用的配置再备份一份。向别人求助时，给出四样脱敏信息就够了：客户端或核心版本、报错的完整一行、故障发生在哪个阶段、已经做过的对照结果。密钥、密码、UUID、真实服务器地址一律不要贴出来。
一句话总结：备份与校验在前，debug 日志定位在中，单变量对照验证在后。日志先告诉你它属于哪一类，你再去修那一类——顺序反过来，就是换一圈节点还停在原地。
参考：Reality 握手公开报告，见 VLESS REALITY outbound fails against Xray-core v26.9.8+。