跨越网络 - 全球网络加速服务商

sing-box DNS 设置与连接排查：从配置到 TUN 逐层定位

更新于 2026-11-01 · kuayue2.online

简答：sing-box 出现“能启动但打不开网页”“DNS resolution failed”或 TUN 下部分应用异常时，先备份配置并运行 sing-box check，再判断是 DNS 查询、DoH/DoT 上游自身解析、节点握手、系统代理还是 TUN 路由问题。当前官方配置参考中，1.14.0 起新增或调整了 dns_mode、dns_address、optimistic、timeout 等字段，旧版字段不能直接套用。

定义：sing-box DNS 排查，是对 DNS 配置、上游解析依赖、代理出站、系统代理和 TUN 接管范围进行分层验证，而不是单纯更换 DNS 地址。

先试这一步：备份、校验，再看第一条错误日志

本文是第三方使用指南站，内容按 sing-box 官方配置参考整理；客户端封装、核心版本和图形界面可能不同。先复制一份当前配置作为回滚文件，例如保存为 config.backup.json，不要直接在原文件上连续修改。

  1. 确认当前核心版本：运行 sing-box version；若客户端内置核心，查看客户端的核心信息页。未显示具体版本时，不要把旧教程中的字段当作通用配置。
  2. 先执行 sing-box check --help，核对当前构建是否支持配置文件参数；支持时再运行 sing-box check -c config.json。官方文档确认存在 sing-box check 检查命令，配置格式和字段以当前 schema 为准。查看官方配置引言与检查命令
  3. 启动后把日志级别临时改为 debug，记录第一条 ERROR 或 FATAL，不要只看最后一条超时。日志支持 trace、debug、info、warn、error、fatal 等级别。查看官方日志字段说明

判断原则：配置校验失败先修字段；出现 DNS resolution failed 先查解析链；出现 connect timeout 或 TLS 握手错误再查节点、端口和出站；出现 permission denied 或 TUN 无法启动则查系统权限与网络扩展。

最小可测试 DNS 配置：先用 local，再逐项增加 DoH 或代理 DNS

下面是按当前官方 JSON 结构组织的最小结构示例，用于验证 DNS 模块能否加载；它不是完整代理订阅，也不包含节点出站，因此不能单独承担代理连接任务。将它合并到现有配置前，必须先确认当前核心版本、字段 schema 和客户端是否允许手动编辑。

{"log":{"level":"debug","timestamp":true},"dns":{"servers":[{"type":"local","tag":"local"}],"final":"local","strategy":"prefer_ipv4"},"inbounds":[],"outbounds":[],"route":{}}

  • 需替换或补齐：现有配置中的 inbounds、outbounds 和 route 不能为了测试永久删除；上例只用于确认 JSON 结构和 DNS 字段。
  • 可观察结果：check 无错误，启动日志没有字段未知、类型错误或 DNS server tag 不存在。
  • 回滚：停止客户端，恢复 config.backup.json，再重新导入或启动，不要把试验字段留在订阅生成的配置中。

官方 DNS 模块使用 servers、rules、final 和 strategy；final 是默认 DNS server tag，strategy 可使用 prefer_ipv4、prefer_ipv6、ipv4_only 或 ipv6_only。查看官方 DNS 配置字段

不要把旧版本中的 dns_mode、dns_address、reverse_mapping 或旧式 DNS server 写法当作所有版本都支持。官方资料显示，旧 DNS server 格式在 1.14.0 已移除；independent_cache 在 1.14.0 已标记弃用。查看官方弃用与移除说明

DoH、DoT 上游为什么会自己解析失败：看 domain_resolver、detour 和 DNS 循环

使用 DoH 或 DoT 时，要区分两件事：第一件是 sing-box 为用户请求解析目标域名；第二件是 sing-box 先解析 DoH/DoT 服务器自己的域名，再建立 HTTPS 或 TLS 连接。第二件失败时，即使代理节点本身可用，DNS 也可能报错。

配置关系实际作用排查动作
final没有命中 DNS 规则时使用的默认 DNS server确认 tag 与 servers 中的 tag 完全一致
detourDNS 请求连接哪个上游出站确认出站 tag 存在，避免把 DNS 又送回会依赖该 DNS 的链路
domain_resolver解析 DoH/DoT server 字段中的域名为域名形式的上游指定可用 resolver，或先用 IP 做隔离测试
代理 DNS通过代理出站连接 DNS 上游先确认代理节点握手成功，再判断 DNS 服务器是否可达

以新版 HTTPS DNS server 为例，如果 server 写的是域名，就必须考虑 domain_resolver；新版结构使用 Dial Fields，而不是旧格式中的 address_resolver。查看官方 DoH server 与 domain_resolver 说明

可用下面的依赖图理解循环：用户域名 → DNS server → DoH 域名解析 → domain_resolver → 出站 → 网络。如果 domain_resolver 又指向同一个需要 DoH 才能工作的上游，就可能形成循环。排查时先换成 local 或已知可用的独立 resolver 验证；验证完成后再恢复代理 DNS，并每次只改一个变量。

现象—原因—动作：不要把 DNS、节点和 TUN 混成一个问题

现象优先怀疑具体动作
配置无法启动字段版本、类型或 tag 错误运行 check，删除最近新增字段，按当前官方 schema 逐项恢复
DNS resolution failedDNS server 不可达、上游自解析失败或循环依赖先切换到 local，再单独测试 DoH/DoT；记录失败的 server tag
域名能解析但网页打不开节点握手、路由规则、TLS/SNI 或系统代理先测试 IP 连接，再看节点出站日志是否出现 connect、TLS 或 route 错误
只有部分应用失败应用没有走系统代理、UDP 不兼容或未进入 TUN分别测试系统代理和 TUN；检查应用是否被排除、是否需要 VPN 权限
开启 TUN 后所有网络异常auto_route、DNS hijack、strict_route 或回环关闭 TUN 回到系统代理；确认恢复后再逐项开启路由与 DNS 接管
订阅更新失败但旧节点仍可用订阅下载、HTTP 客户端或订阅地址问题把“更新失败”和“节点握手失败”分开记录，不要因更新失败直接判断节点不可用

测试应留下可复现记录：测试时间、网络类型、客户端模式、目标域名、第一条错误、是否能解析、是否开始 TCP/TLS 握手，以及恢复动作。不要公开完整订阅地址、UUID、密码、私钥或令牌。

TUN 与系统代理：Windows、macOS、Android、iOS 分开检查

  • Windows：先关闭 TUN，仅启用系统代理测试；再开启 TUN。若开启 strict_route 后虚拟机或特殊网络应用异常，先回滚该字段并查看日志。官方说明指出，Windows 下 strict route 可阻止普通多网卡 DNS 泄漏，但也可能影响部分应用。查看官方 TUN、dns_mode 与 strict_route 说明
  • macOS：检查客户端的网络扩展或 VPN 权限是否仍为允许状态；分别测试系统代理与 TUN。官方 DNS 文档特别提醒，reverse_mapping 依赖应用先解析域名，在 macOS 等系统 DNS 被代理和缓存的环境中可能出现兼容性问题，因此排障时先不要启用它。查看官方 reverse_mapping 说明
  • Android：TUN 通常依赖系统 VpnService；确认 VPN 权限、始终连接或其他 VPN 应用没有抢占连接。Android 图形客户端对部分 TUN 字段存在实现差异，不能仅凭核心文档推断客户端一定支持。查看官方 Android 客户端功能支持表
  • iOS：检查 VPN 配置是否允许、是否同时启用了其他网络扩展，并分别验证“系统代理可用”和“TUN 可用”。如果只有部分应用失败，记录应用是否使用 UDP、是否被分流规则排除；无法从客户端日志确认时，结论应写为“未核实”，不要直接归因于 DNS。

当前 TUN 文档显示，dns_mode、dns_address 自 1.14.0 起出现；disabled 不配置原生 DNS 也不劫持 DNS，native 配置系统接口 DNS，hijack 还会增加 53 端口劫持。请先确认核心版本，再决定是否使用这些字段。

回滚顺序：恢复可用状态后，再找真正的故障点

  1. 停止 sing-box 或客户端服务。
  2. 恢复备份配置，关闭最近新增的 TUN、DNS 规则、DoH/DoT、FakeIP 和缓存实验字段。
  3. 先用系统代理模式验证节点出站，再验证 DNS，最后才重新开启 TUN。
  4. 每次只恢复一个模块：先 local，再远程 DNS，再 DNS rules，最后是 DNS hijack 或复杂路由。
  5. 恢复后重新运行当前构建支持的 check，并保存启动日志。

如果回滚后仍失败，优先核对客户端是否自动覆盖手工配置、订阅是否生成了旧字段、系统是否存在其他 VPN 或代理，以及当前网络是否允许访问节点端口。没有日志或可复现记录时，不要把问题确定为 DNS。

推荐入口

如果你已经完成配置校验，仍需要按网络、节点和客户端模式记录连接结果，可在整理好脱敏信息后使用边界云加速的相关服务入口，具体功能与适用范围以官网为准。

常见问题

sing-box 的 dns_mode 可以直接写 disabled、native 或 hijack 吗？

不能脱离版本直接照抄。官方 TUN 文档标注这些字段自 1.14.0 起出现，且作用与 auto_route、strict_route、auto_redirect 和平台有关。先确认核心版本与当前 schema，再用 check 验证。

DoH 的 server 已经写了域名，为什么还要 domain_resolver？

DoH 连接建立前，sing-box 仍要先把 DoH server 的域名解析成 IP。新版 HTTPS DNS server 文档要求域名形式的 server 考虑 domain_resolver；如果 resolver 又依赖同一个 DoH 上游，就可能出现循环。

DNS 能解析，但 TUN 模式下网页仍打不开，下一步查什么？

先关闭 TUN，仅用系统代理测试。如果系统代理可用而 TUN 不可用，重点查 auto_route、dns_mode、dns_address、strict_route、VPN 权限和其他网络扩展；如果两种模式都失败，再查节点端口、TLS/SNI 和路由规则。

sing-box check 通过后，为什么客户端仍然无法连接？

check 主要验证配置结构和字段，不能证明远端节点、DNS 上游、系统权限或网络端口可达。通过后仍要看启动日志，确认 DNS 查询、节点握手和应用流量分别进入了哪一层。

相关阅读

参考资料

  1. sing-box 官方配置引言与 check 命令
  2. sing-box 官方 DNS 配置参考
  3. sing-box 官方 DoH server 与 domain_resolver 说明
  4. sing-box 官方 TUN、dns_mode、dns_address 与 strict_route 说明
  5. sing-box 官方日志配置说明
  6. sing-box 官方弃用与移除说明
  7. sing-box 官方 Android 客户端功能支持表