sing-box 连接失败怎么检查配置和日志？
简答：sing-box 连接失败，先判断是配置没有启动、节点握手失败，还是客户端运行后网页访问失败。最快的排查顺序是：备份配置→运行 sing-box check 校验→打开 debug 日志→根据 timeout、connection refused、DNS resolution failed、handshake failure 等关键词分流→用单节点和单目标复测。本文为第三方使用指南，不代表任何客户端或服务项目的官方页面。
定义：sing-box 连接失败排查，是通过配置校验、启动日志、本地监听端口、DNS解析、TLS参数、路由和TUN权限逐层确认故障所在阶段的过程。
先做这一步：备份配置并运行检查命令
如果 sing-box 完全无法启动，优先检查配置文件，而不是先修改节点参数。sing-box 官方文档说明其配置使用 JSON，并提供 check 检查、format 格式化和 merge 合并命令；配置顶层通常包括 log、dns、inbounds、outbounds 和 route 等部分，具体字段应以当前版本文档为准。可先查看官方配置说明。
- 复制一份原配置作为回滚文件，不要直接覆盖原文件。
- 确认配置文件路径、文件名和工作目录，避免命令检查的不是客户端实际加载的文件。
- 在当前 sing-box 构建的帮助信息中确认参数写法，再执行类似
sing-box check -c config.json的检查。这里的命令是结构示例，实际参数以当前构建的sing-box check --help和官方文档为准。 - 如果检查失败，先修复 JSON 逗号、括号、字段类型、文件路径和引用文件权限，不要同时修改 DNS、TLS 和路由。
检查通过只代表配置能够被解析和加载，不代表远端节点可达、认证参数正确或网页一定能打开。下一步必须结合启动日志和实际连接测试。
按故障阶段判断：你看到的现象对应哪一层
| 现象 | 优先判断 | 下一步 |
|---|---|---|
| 启动后立即退出 | 配置解析、字段兼容、路径或权限 | 先备份，再运行 check，查看最早出现的 error 或 fatal |
| 配置能保存但服务无法启动 | 本地端口冲突、TUN权限、系统扩展或文件权限 | 暂时关闭TUN，改用普通本地代理或检查监听端口 |
| 节点连接超时 | 域名解析、远端端口不可达、路由或网络质量 | 单独测试节点域名和端口，记录是否每次都超时 |
| connection refused | 目标端口主动拒绝，或本地端口没有服务监听 | 区分本地监听端口与远端节点端口，分别检查 |
| handshake failure | TLS、SNI、ALPN、Reality或认证参数不匹配 | 逐项核对服务端提供的参数，避免凭经验改字段 |
| DNS resolution failed | DNS服务器不可用、规则选择错误或域名本身无法解析 | 检查 dns.servers、DNS规则、最终服务器和解析日志 |
| 服务运行但浏览器打不开 | 系统代理未生效、浏览器未使用代理、路由或TUN未接管 | 先测试本地代理端口，再检查系统代理和TUN状态 |
| permission denied | 配置文件、日志文件、TUN设备或系统网络权限不足 | 确认文件可读写，并按平台要求授予网络或VPN权限 |
不要只看最后一行日志。启动失败时，最早出现的 error 或 fatal 往往比后续的连锁报错更接近根因；如果日志只有简略信息，可临时提高日志级别。
如何打开和保存 sing-box 日志
官方日志配置支持 trace、debug、info、warn、error、fatal 和 panic 等级别，也可以通过 output 指定日志文件；指定输出文件后，日志不会继续写入控制台。字段定义可参考官方日志文档。
排查时建议临时使用 debug，复现一次后立即恢复为较低日志量，避免长期保存不必要的信息。结构示例如下，仅用于说明字段位置，不建议未经核对直接复制：
{
"log": {
"level": "debug",
"timestamp": true,
"output": "box.log"
}
}- Windows、Linux和macOS：如果使用命令行运行，优先在启动终端观察输出；如果使用图形客户端，使用其日志或Dashboard页面导出相关时间段。
- Android和iOS：通过所用图形客户端的日志、诊断或运行状态页面收集；不同客户端界面名称可能不同，不能把某一客户端菜单路径套用到全部客户端。
- 记录复现时间、系统、客户端类型、核心版本、使用的配置文件名称、错误关键词和是否开启TUN。
- 提交日志前删除订阅令牌、完整订阅地址、UUID、密码、私钥、API密钥以及可识别的内网地址。
官方图形客户端页面说明，Windows、Linux、Android和Apple平台存在对应的图形客户端，但第三方图形客户端的日志入口和功能可能不同，具体应以所用客户端文档为准，可先查看官方图形客户端说明。
配置校验通过后，按字段清单继续查
1. 检查 inbounds 与本地代理端口
inbounds负责接收本机应用流量。确认其类型、监听地址、端口和协议与客户端实际设置一致。假如浏览器设置的是本地端口A，而配置实际监听端口B，就会出现客户端看似运行、浏览器却无法访问的情况。可先使用系统的端口查看工具确认该端口是否被 sing-box 监听；工具命令因操作系统不同，先以系统帮助为准。
2. 检查 outbounds 与默认出站
outbounds负责连接目标或远端节点。确认使用的出站标签存在，分流规则引用的标签没有拼写错误，并确认默认出站不是误设为直连。若配置包含选择器或URL测试组，先固定到一个明确的单节点，避免自动选择导致每次复现结果不同。
3. 检查 DNS 服务器、规则和最终服务器
官方DNS配置包含服务器列表、规则、最终服务器和解析策略等字段；final为空时会使用列表中的第一个服务器。相关字段可参阅官方DNS配置文档。重点检查：DNS服务器标签是否存在、规则是否把目标域名送到错误服务器、是否启用了不匹配当前网络的IPv4或IPv6策略，以及DNS请求是否被错误路由。
4. 检查 TLS、SNI、ALPN 和认证
出现 handshake failure、证书验证失败或连接建立后立即断开时，核对服务端提供的服务器名称、ALPN、证书校验方式、Reality相关字段和认证信息。官方TLS文档说明，server_name既用于证书主机名校验，也可能用于TLS握手中的虚拟主机支持；因此不能把它随意替换成节点IP。字段和版本变化应以官方TLS文档为准。
最小化复测：把复杂配置缩小到一个节点
- 先关闭自动选节点、复杂规则集、远程规则和TUN，只保留一个本地入站、一个明确出站、必要的DNS和最少路由。
- 使用一个固定域名或目标地址进行测试，记录启动时间、连接开始时间、成功或失败时间。
- 如果单节点可用，再一次只恢复一个功能：先恢复DNS规则，再恢复分流规则，最后恢复TUN或系统代理。
- 每恢复一项就复测一次；哪一步重新出现错误，重点检查该部分及其引用的标签。
- 如果单节点仍然超时，分别测试节点域名解析、本地网络到远端端口的连通性和TLS握手，不要通过反复改配置来掩盖远端不可达问题。
这种二分式复测可以区分“节点参数问题”和“复杂路由、DNS或TUN问题”。不要把一次成功当作长期稳定性证明，至少应在不同时间重复记录结果。
TUN、系统代理和路由环回怎么查
如果普通本地代理可以访问，但开启TUN后失败，优先检查VPN权限、路由是否指向TUN、DNS是否被正确接管，以及是否存在其他VPN、代理软件或安全软件冲突。官方TUN文档指出，auto_route会把默认路由设置到TUN；为避免流量环回，可配置自动检测接口、默认接口或出站绑定接口，具体取决于平台和配置结构，详见官方TUN配置文档。
- 先关闭其他VPN、代理和网络过滤工具，再复测。
- 确认系统已经授予客户端VPN或网络扩展权限；移动端需要重新确认VPN连接授权。
- 检查是否同时启用了多个TUN或多个网络接管组件。
- 若只有部分应用失败，确认这些应用是否使用系统代理；官方客户端说明指出，系统代理主要覆盖支持HTTP代理的应用，UDP、ICMP以及不读取系统代理的程序可能不会经过该路径，可参考官方客户端工作方式说明。
修复后仍然无法确定原因时，先回滚到备份配置，恢复“一个入站、一个出站、关闭TUN”的最小状态，再逐项加回功能。
提交求助前的安全信息清单
有效的故障报告应让别人能够复现问题，但不应暴露订阅或身份凭据。建议保留以下信息：
- 操作系统及版本、sing-box核心版本、图形客户端名称和版本。
- 配置校验是否通过，使用的配置文件类型，以及错误发生的准确时间。
- 完整的第一处 error 或 fatal 附近日志，并说明是否每次都出现。
- 是否开启TUN、系统代理、IPv6、DNS规则、TLS或特定传输。
- 最小化配置的复测结果：单节点是否可用、浏览器是否可用、其他应用是否可用。
必须删除订阅Token、带认证信息的URL、UUID、密码、私钥、API密钥和个人IP。若需要公开配置结构，可将真实值替换成 example.com、REDACTED 或随机占位符，并明确说明哪些字段已脱敏。
常见问题
sing-box check 通过了，为什么还是连接失败？
check主要用于确认配置能够被解析和加载；它不能证明远端节点可达、TLS参数正确、DNS可用或系统流量已经进入代理。因此下一步要看运行日志，并用单节点、单目标进行复测。
日志里的 timeout 一定代表节点失效吗？
不一定。timeout可能发生在域名解析、本地到远端端口、TLS握手或目标网站访问阶段。先结合日志中的目标地址和阶段判断，再分别测试DNS、端口和握手；不要只凭一次超时下结论。
看到 connection refused 应该改DNS吗？
通常不应直接改DNS。先判断被拒绝的是本地代理端口还是远端节点端口：前者检查入站监听和端口占用，后者检查节点地址、端口、服务端状态和网络路径。
为什么普通代理能用，开启TUN后反而打不开？
这通常说明问题集中在VPN权限、默认路由、DNS接管、路由环回或其他网络工具冲突，而不一定是节点参数错误。先关闭TUN验证普通代理，再按TUN文档检查路由和权限。
日志可以直接发到群里求助吗？
不建议。日志可能包含订阅地址、认证信息、UUID、私钥和内网地址。应先脱敏，只保留版本、错误时间、错误关键词、配置结构和最小化复测结果。
常见问题
sing-box check 通过了，为什么还是连接失败？
配置校验通过只代表文件可解析和加载，不代表节点可达、TLS参数正确、DNS可用或系统流量已经进入代理。还需要查看运行日志，并用单节点、单目标复测。
timeout 一定说明节点失效吗？
不一定。timeout可能发生在DNS解析、本地到远端端口、TLS握手或目标访问阶段。应结合日志目标和发生阶段，分别测试DNS、端口和握手。
connection refused 应该先改DNS吗？
不建议直接改DNS。先判断拒绝发生在本地代理端口还是远端节点端口，再分别检查监听状态、端口占用、节点地址和服务端参数。
为什么普通代理能用，TUN模式却打不开？
优先检查VPN权限、默认路由、DNS接管、路由环回以及其他VPN或网络工具冲突。可以先关闭TUN确认普通代理是否正常，再逐项恢复。
如何安全提交 sing-box 日志？
删除订阅Token、认证URL、UUID、密码、私钥、API密钥和个人IP，只保留版本、错误时间、错误关键词、配置结构和最小化复测结果。