sing-box 连接不上网络怎么排查？从日志到 DNS、TUN 的完整步骤
简答：sing-box 连接不上网络时，先看日志并执行配置检查，再按“配置—节点—DNS—路由—TUN—目标网站”顺序定位。网页打不开不一定是节点失效，也可能是本地端口、系统代理、VPN 权限或路由规则没有生效。
定义：sing-box 连接问题排查，是根据故障发生阶段和日志关键词，依次验证配置格式、订阅内容、节点握手、DNS 解析、路由接管与目标网站访问的过程。
先做这 5 分钟速查：判断到底是哪一层出错
先不要重装 sing-box，也不要同时更换节点、DNS 和规则。按照下面顺序做一次单变量检查：每完成一项就重新连接并记录结果。sing-box 使用 JSON 配置，官方文档提供了配置检查和格式化命令；图形客户端则通常在配置、日志或关于页面中显示核心版本和运行状态。可先查看官方配置结构说明与官方日志配置说明。
| 现象 | 优先判断 | 先做什么 |
|---|---|---|
| 客户端一启动就退出 | 配置 JSON、字段废弃、版本不兼容或权限 | sing-box check -c config.json，再看第一条 fatal/error |
| 有节点但一直超时 | 服务器地址、端口、网络可达性或协议参数 | 核对地址与端口，并测试 TCP/UDP 是否能到达 |
| 节点显示已连接，但网页打不开 | DNS、系统代理、路由或 TUN 没有接管 | 先访问一个域名和一个 IP，再查看命中日志 |
| 只有部分应用不能用 | 分应用路由、应用绕过 VPN 或代理协议不兼容 | 暂时关闭应用排除规则，使用同一网络复测 |
| 只有一个网站打不开 | 目标网站、IPv6、TLS 或该域名规则异常 | 换另一个域名对比，不要立即判定整个节点失效 |
截至 2026-10-24，官方文档仍持续记录配置字段变化。不要直接把旧教程里的 DNS、TUN 或规则字段复制到新配置；先以客户端显示的核心版本和对应的官方文档为准。
第一步：确认订阅、配置格式和核心版本
如果问题发生在“导入订阅”阶段，先把它和“导入成功但运行失败”分开处理。打开订阅链接时，确认返回的是 sing-box 可识别的 JSON 配置，而不是登录页、HTML 错误页或其他客户端专用的 YAML。订阅链接包含账号凭据时，不要把完整链接粘贴到公开 Issue、群组或截图中。
- 检查文件是否完整：用文本编辑器打开配置，确认最外层是 JSON 对象，常见顶层字段包括
log、dns、inbounds、outbounds和route。官方配置说明明确 sing-box 使用 JSON 配置。 - 执行配置检查：命令行配置可运行
sing-box check -c config.json。如果图形客户端不允许直接执行命令，就在客户端的配置验证、启动日志或核心日志中寻找 JSON 解析错误、未知字段和缺少必填字段。 - 看第一条错误：不要只看最后的“启动失败”。例如 JSON 逗号错误、字段拼写错误、被移除的旧字段，会在后续引发端口、DNS 或路由连锁报错。
- 确认版本与配置来源匹配：官方迁移文档记录了 DNS 服务器格式、旧版 GeoIP/Geosite、TUN 地址字段、WireGuard outbound 等变化。若配置来自旧客户端或旧教程，优先按照迁移文档改字段，不要只删除报错字段。
如果配置检查通过但仍无法访问，说明故障已经进入运行阶段，下一步应看本地入站、节点出站和系统接管，而不是继续修改 JSON。
参考：sing-box 配置结构、sing-box 迁移说明。
第二步：看日志关键词，区分节点、端口、TLS 与 DNS
日志是排查 sing-box 连接问题的最短路径。官方日志配置支持 trace、debug、info、warn、error 和 fatal 等级，也可以写入文件。排错时可临时提高日志等级，复现一次后恢复，避免长期记录过多敏感信息。
| 日志或现象 | 通常说明 | 下一步 |
|---|---|---|
connection refused | 目标地址主动拒绝，或本地/服务器端口没有监听 | 检查端口监听、服务状态、防火墙和安全组 |
timeout | 连接在规定时间内没有完成，可能是路径、端口、UDP 或服务器不可达 | 换网络复测，并分别测试 TCP 与 UDP 条件 |
handshake failure | TLS、Reality、协议参数或服务端握手不匹配 | 核对 server_name、SNI、public_key、short_id、fingerprint 等字段 |
DNS lookup failed | 域名解析失败、DNS 服务器不可达或 DNS 路由错误 | 先用 IP 访问对比，再检查 DNS server、规则与劫持设置 |
authentication failed | UUID、密码、用户名或密钥不匹配 | 重新复制凭据，确认没有多余空格或截断 |
| 日志显示 direct，但网页打不开 | 规则把请求送到了直连，或目标网络本身不可达 | 查看该域名命中的规则与最终 outbound，不要只看 VPN 图标 |
日志中出现节点地址、UUID、密码、私钥、订阅链接和完整域名时，分享前应打码。不要为了“测试”关闭 TLS 校验、公开 API 密钥或把完整配置上传到不可信网站。
Linux 使用 systemd 管理服务时，可查看服务日志：sudo journalctl -u sing-box --output cat -e；持续观察可用 sudo journalctl -u sing-box --output cat -f。官方安装文档也说明了这些服务管理方式。
参考：日志配置、安装与 systemd 日志。
第三步：检查本地端口、系统代理和服务监听
使用 mixed 入站时，sing-box 可以提供 SOCKS 和 HTTP 服务；只有客户端真正把浏览器或应用流量送到这个入站，网页请求才会进入 sing-box。官方 mixed 文档说明，set_system_proxy 可在支持的平台自动设置系统代理，但图形客户端也可能由自己的设置页接管。
- 确认监听地址与端口：查看配置或客户端设置中的
listen和listen_port。常见本地代理端口为 7897 或 7890，但必须以设置页为准。 - 确认系统代理一致：Windows、macOS 或 Linux 的系统代理地址通常应是
127.0.0.1加对应端口。若客户端只启用了 TUN，系统代理开关未必是判断依据；反之，只开系统代理而应用不遵循系统代理，也会表现为无法上网。 - 检查端口是否被占用：Linux 可使用
sudo ss -lntup；macOS 改用lsof -nP -iTCP -sTCP:LISTEN；Windows 可使用netstat -ano。若端口被其他程序占用，改客户端端口或停止冲突进程。 - 做最小化验证：只保留一个本地入站和一个可确认的出站，关闭复杂规则后测试。若最小配置可用，再逐项恢复 DNS、规则集和 TUN。
端口监听正常，只能说明本机有程序接收请求，不能证明节点握手成功。要继续看连接日志里是否出现该请求、命中了哪个策略，以及最终使用了哪个 outbound。
第四步：按平台排查 TUN、VPN 权限和网络冲突
TUN 模式与普通系统代理不是同一条链路。TUN 需要创建虚拟接口并配置路由；如果权限不足、其他 VPN 正在占用 VPN 通道、系统防火墙拦截，或者默认路由没有切换，客户端可能显示运行中但应用仍无法访问。
| 平台 | 重点检查 | 处理动作 |
|---|---|---|
| Windows | TUN 服务模式、管理员权限、Windows 防火墙、其他 VPN | 以管理员权限启动或安装客户端需要的服务；暂时关闭其他 VPN，检查 TUN 与 DNS 设置 |
| macOS | 系统扩展、隐私与安全性放行、系统代理和 VPN 配置 | 在系统设置中允许相关网络扩展；若下载程序被隔离，按系统提示完成放行后重新启动 |
| Linux | root/CAP_NET_ADMIN、专用用户、systemd 服务和路由表 | 检查服务用户是否能读取配置和创建 TUN；查看 ip route、ip rule 与 systemd 日志 |
| Android | VPN 权限、始终开启 VPN、分应用排除、电池优化和其他 VPN | 允许 VPN 请求，暂时取消应用排除，关闭其他 VPN 后用 Wi-Fi 与移动网络分别测试 |
| iOS | VPN 配置授权、按应用规则、网络切换和系统限制 | 重新允许 VPN 配置，关闭可能绕过 VPN 的分流规则，并分别测试 Wi-Fi 与蜂窝网络 |
官方图形客户端列表覆盖 Android、iOS/macOS/Apple tvOS、Windows 和 Linux。sing-box 的 TUN 文档还说明，auto_route 会把默认路由设置到 TUN；Linux 通常建议结合 auto_redirect，而 Windows 的 strict_route 会影响 DNS 泄漏和部分虚拟化软件的网络行为。修改这些选项后要一次只改一个，并记录恢复方法。
如果电脑同时运行 Docker、虚拟机、公司 VPN 或安全软件，先停用其中一个进行 A/B 测试；如果手机在 Wi-Fi 正常、移动网络失败，优先比较 DNS、IPv4/IPv6、运营商网络和 UDP 条件，不要直接归因于配置文件。
第五步：DNS、路由和协议参数的最小化复测
当 sing-box 能启动、本地端口也在监听，但网页仍打不开时，把问题拆成三个测试：解析是否成功、节点是否能建立连接、请求是否被正确路由。这样可以避免把 DNS 故障误判为节点故障。
- 先测域名与 IP：分别访问一个域名和一个已知可用的 IP。域名失败而 IP 成功，优先查 DNS；域名和 IP 都失败，再查节点、路由或目标网络。
- 检查 DNS 规则：查看 DNS 请求是否命中预期服务器，是否被错误的直连、阻断或旧规则集处理。官方文档显示，DNS 规则字段在多个版本中发生过迁移，旧版
geoip、geosite和部分旧 DNS 字段不能直接照搬。 - 检查最终 outbound：不要只看“已连接”状态，要看具体请求的连接日志、命中规则和最终 outbound。若请求被送往
direct，而直连本身不可达，应检查route.final、规则顺序和规则集下载状态。 - 核对协议参数：服务器地址、端口、UUID、密码、TLS 开关、SNI/server_name、Reality public_key、short_id、fingerprint 任何一个不一致，都可能导致握手失败。不要把客户端字段名称与其他内核或其他客户端的字段混用。
- 校准系统时间：TLS 和部分基于证书或握手时间的连接依赖正确系统时间。开启系统自动校时后，完全退出并重新启动 sing-box，再复测一次。
如果只剩 UDP 协议失败，而 TCP 协议正常，重点检查当前网络是否限制 UDP、服务器防火墙和云安全组是否放行对应端口，以及客户端是否真的使用了 UDP 出站。不要用 TCP 测试结果替代 UDP 结论。
复现仍失败时：用最小配置和脱敏信息定位
如果完成上述步骤仍然连接不上，建议建立一个最小化复现：只保留一个入站、一个出站、必要的 DNS 和最少路由规则，关闭复杂 rule-set、分应用规则和自定义 TUN 路由。每次只恢复一个模块，直到问题重新出现，这比同时修改多个字段更容易找到根因。
- 必须保留：客户端平台、核心版本、操作系统版本、故障发生时间、连接网络类型、错误关键词和复现步骤。
- 必须脱敏：订阅 URL、UUID、密码、私钥、Reality private_key、完整域名列表、服务器真实地址和可识别个人信息。
- 不要直接提供：完整原始配置、完整日志文件、账户后台截图或包含授权信息的二维码。
- 最终判定：配置检查失败属于配置层；端口拒绝或超时属于可达性层；握手失败属于协议参数层；DNS lookup failed 属于解析层；日志显示已命中规则但目标不可达，则继续比较路由、目标网站和当前网络。
sing-box 官方支持页面提供了项目支持渠道；提交问题前，应先阅读对应文档并完成脱敏。若问题只发生在某个商业订阅或某个节点，服务端状态、套餐状态和节点可用性需要由对应服务提供方核实，不能仅凭客户端图标下结论。
参考：sing-box 官方支持渠道。
常见问题
sing-box 显示已连接，为什么网页还是打不开？
“已连接”通常只表示客户端或节点状态正常，不代表所有应用流量都经过 sing-box。先查看连接日志是否出现请求、命中的规则和最终 outbound，再检查系统代理、TUN 权限、DNS 与应用排除规则。
sing-box 连接超时，是节点失效还是本地网络问题？
单凭 timeout 不能直接判定。先用同一网络测试其他节点，再切换 Wi-Fi 与移动网络；同时核对服务器地址、端口、TCP/UDP 类型、防火墙和安全组。如果不同网络结果不同，优先查当前网络路径或协议限制。
配置检查通过，但 sing-box 仍然无法上网怎么办？
配置检查通过只说明 JSON 和字段基本可解析，不能证明节点可达、握手成功或流量已被接管。继续看运行日志，依次检查本地端口、节点握手、DNS、路由、TUN/VPN 权限和最终出口。
为什么只有部分应用不能通过 sing-box？
常见原因包括分应用代理或排除规则、应用不遵循系统代理、IPv6/UDP 行为不同，以及其他 VPN 或安全软件拦截。先关闭应用排除和复杂规则，用同一网络对比一个浏览器与一个受影响应用。
分享 sing-box 日志时需要隐藏哪些内容？
至少隐藏订阅链接、UUID、密码、私钥、Reality 密钥、服务器真实地址、完整个人域名和账户信息。保留平台、核心版本、错误关键词、时间和脱敏后的配置结构即可。