sing-box DNS 配置怎么排查？从配置校验到连接测试
简答：sing-box DNS 排查不要先改一堆字段：先备份实际加载的配置，确认客户端和内核版本，再运行 sing-box check 区分“配置解析失败”和“运行时 DNS 不通”。如果校验通过，继续检查 servers[].tag 与 dns.rules[].server 是否一致、dns.final 是否存在，以及 DoH/DoT 的 domain_resolver 是否形成循环依赖。
定义：sing-box DNS 配置排查，是把问题拆成配置格式、DNS 规则匹配、上游服务器连通性、节点域名解析和 TUN/系统 DNS 接管五层逐项验证。
先做这 4 步：确认配置到底有没有被正确加载
本文是面向 sing-box 使用者的第三方使用指南，不代表 sing-box 或任何客户端项目的官方说明。sing-box 使用 JSON 配置，官方文档提供了 check、format 和 merge 等配置处理命令；DNS 主配置位于 dns 字段下。可先查看官方配置结构与命令说明。
- 备份配置：复制当前实际加载的 JSON 文件，保留原文件名和目录。不要直接在订阅生成文件上反复覆盖修改。
- 确认实际文件：在客户端设置或启动参数中确认正在加载的文件。若使用多个配置目录，还要确认工作目录和配置目录没有弄错。
- 确认版本：记录客户端名称、sing-box 内核版本、系统平台和故障发生时间。字段兼容性必须以当前构建的官方文档为准。
- 先校验：在当前构建中运行
sing-box check --help查看参数，再执行类似sing-box check -c config.json的检查。若当前构建不接受该参数，按帮助输出改用对应写法。
结果判断：check 报 JSON、字段、类型或未知字段错误，说明问题还在配置层；check 通过，只能说明配置通过静态检查，不能证明 DNS 上游、节点域名或 TUN 路由一定可达。
如果需要整理配置，可先使用官方支持的 format 命令，但应先复制文件再操作，例如 sing-box format -w -c config.json -D config_directory。命令格式可参考sing-box 官方配置文档。
| 现象 | 优先检查 | 暂时不要做的事 |
|---|---|---|
| 启动即退出 | JSON 语法、字段名、版本兼容性、引用的 tag | 不要先改 TUN 或系统 DNS |
| 启动正常但域名打不开 | DNS 上游连通性、规则命中、dns.final | 不要只凭网页结果判断 DNS |
| 节点域名无法解析 | 节点使用的 domain_resolver、上游地址和端口 | 不要把节点故障直接归因于 FakeIP |
| 开启 TUN 后断网 | dns_mode、端口 53、路由和系统 DNS 接管 | 不要同时改多个平台选项 |
检查 servers、rules、final：最常见的引用错误
DNS 服务器由 dns.servers 定义，每个服务器有自己的 tag；DNS 规则通过动作将请求路由到服务器。官方 DNS Server 文档列出了 local、udp、tcp、tls、https、fakeip 等服务器类型，具体字段应以官方 DNS Server 文档为准。
- 逐字核对 tag：例如服务器使用
"tag": "local-dns"，规则中的server就必须引用完全相同的local-dns。大小写、连字符和下划线都不能凭感觉修改。 - 检查 dns.final：
final是没有其他规则命中时使用的默认 DNS 服务器 tag；如果为空，官方文档说明会使用列表中的第一个服务器。因此，修改 servers 顺序可能改变默认行为。 - 检查规则顺序：规则按列表顺序处理时，前面的宽泛规则可能先匹配，导致后面的域名规则看起来“不生效”。先暂时保留一条最小规则验证，再逐条恢复。
- 确认字段归属：较新的配置将规则动作放在
action中，传统直接写在规则对象里的部分字段可能已经弃用。官方 DNS Rule 文档列出了不同版本的变更和弃用字段。
排查时可以做一个最小化对照：只保留一个能确认类型的 DNS server、一个引用该 tag 的 route 动作和一个 final，先让配置通过 check，再逐步加回分流规则。最小配置只是结构示例，不可直接复制到生产环境，其中的服务器地址、tag、入站和出站都必须替换并按当前版本文档核对。
{"dns":{"servers":[{"type":"local","tag":"local-dns"}],"rules":[{"domain_suffix":["example.com"],"action":"route","server":"local-dns"}],"final":"local-dns"}}
官方文档还说明，DNS route 动作的 server 必须指向已定义的服务器 tag；可查看DNS Rule Action 文档核对当前写法。
DoH、DoT 和节点域名：重点排查 domain_resolver 与 detour
如果 DNS 上游本身使用域名，例如 HTTPS DNS 服务的 URL 是域名形式，sing-box 还需要先把这个上游域名解析成 IP。官方 HTTPS DNS 文档明确说明：当地址使用域名时，还需要设置 domain_resolver；否则可能出现上游无法建立连接，或者配置在解析链路上互相等待。
- 先看上游地址：区分上游是 IP 地址还是域名。IP 地址可以减少首轮引导解析问题，但不代表 TLS 主机名、证书和网络路径一定正确。
- 再看 domain_resolver：它用于解析 DNS 上游或出站目标使用的域名。不要把它误认为是“让所有请求走某个代理”的开关。
- 再看 detour：
detour描述连接使用的出站路径，domain_resolver描述域名解析使用的 DNS 服务器；两者作用不同，不能互相替代。 - 防止循环依赖：如果 DoH 上游的域名要用该 DoH 自己解析，就会形成循环。应为引导解析准备一个可达的解析器，并确认该解析器不会再次依赖同一条尚未建立的链路。
sing-box 官方 Dial Fields 文档指出，在较新的版本中，使用域名作为服务器地址的出站或端点需要配置域名解析器，只有配置了单一 DNS 服务器等情况下可能省略。具体兼容性应查看官方 Dial Fields 文档。
可观察结果应写清楚：如果上游 IP 和端口可达，但上游域名解析失败，优先查 domain_resolver；如果域名能解析但 TLS 握手失败，继续查端口、证书、SNI、系统时间和出站路径，不要继续改 DNS rules。
用 nslookup、dig 和端口测试区分 DNS 不通还是节点不通
静态 check 通过后，要测试 DNS 上游本身，而不是只打开一个网页。下面命令用于观察，不代表它们一定能测试到 sing-box 内部选中的 DNS server；测试前要记录系统当前 DNS、目标域名、网络类型和时间。
- Windows：使用
nslookup example.com查看系统解析器和返回结果；也可以使用nslookup 节点域名单独测试节点域名。 - macOS/Linux：优先使用
dig example.com；使用dig 节点域名检查节点域名是否能获得地址。 - 指定解析器对照：在支持该写法的系统中使用
nslookup example.com DNS服务器地址或dig @DNS服务器地址 example.com，将系统解析结果和指定解析器结果分开记录。 - 测试 TCP 端口：Windows PowerShell 可用
Test-NetConnection 节点域名 -Port 端口；macOS/Linux 可用当前系统支持的 TCP 端口测试工具。端口可达只说明 TCP 建连可能成功，不能证明协议、认证或 TLS 一定正确。 - 测试代理入口：如果配置提供本地 HTTP 或 SOCKS 入站，用客户端实际监听地址和端口执行请求测试；不要把“浏览器能打开”当作 DNS 规则已经按预期命中。
| 关键词或现象 | 优先动作 | 结论边界 |
|---|---|---|
| unknown field、decode、invalid character | 核对 JSON、字段拼写和当前版本文档 | 属于配置解析问题 |
| server not found、unknown DNS server | 核对 rules 引用的 tag 和 servers 列表 | 不能说明上游网络一定故障 |
| i/o timeout、context deadline exceeded | 测试上游地址、端口、出站路径和超时 | 可能是网络或上游不可达 |
| 握手失败、证书错误 | 检查 TLS 主机名、系统时间、端口和域名解析 | 不应只修改 DNS final |
| 节点域名解析失败 | 检查出站的 domain_resolver 和节点域名 | 可能与 DNS rules 分流无关 |
FakeIP、IPv4/IPv6 与 TUN：DNS 已通但应用仍打不开
如果命令行解析正常，但开启 TUN 后应用仍无法访问，重点转向 DNS 接管、路由和地址策略。官方 TUN 文档说明，较新版本提供 dns_mode，包括 disabled、native 和 hijack；启用自动路由时，默认行为可能与未启用时不同。请按当前客户端实际支持的字段核对官方 TUN DNS 文档。
- 先关闭变量：临时关闭 FakeIP、复杂分流和 IPv6 偏好，只保留一个可验证的 DNS 服务器，确认基础访问恢复后再逐项启用。
- 检查 strategy：对比
prefer_ipv4、prefer_ipv6、ipv4_only和ipv6_only的实际效果。若网络没有可用 IPv6，优先检查是否误设为仅 IPv6。 - 检查端口 53：TUN 接管 DNS 时，确认系统中没有其他程序占用预期监听端口，也确认防火墙没有阻断本地 DNS 请求。
- 检查系统 DNS：Windows 查看当前网卡 DNS，macOS 查看当前网络服务 DNS，Android/iOS 则检查客户端是否具备对应的 VPN/TUN 权限。不同客户端的菜单名称可能不同，不能把桌面端字段直接套到移动端。
- 逐项恢复：每次只恢复一个功能，记录“修改前、修改后、日志第一条异常和解析结果”。一旦复现，就回滚最后一次修改。
FakeIP 并不是所有 DNS 故障的默认答案。只有当日志、规则或应用行为明确指向地址映射、返回地址策略或 TUN 接管时，才进入 FakeIP 专项检查。先验证普通 DNS 查询、节点域名和本地代理入口，可以避免把多个问题混在一起。
版本升级后的 DNS 迁移与回滚清单
官方 DNS 文档显示，不同 sing-box 版本会新增、移动或弃用字段。例如，independent_cache在 1.14.0 已标记为弃用，官方说明计划在 1.16.0 移除；optimistic缓存和 DNS 查询默认超时则属于较新的配置能力。版本号和字段可用性必须以当前构建对应的官方 DNS 文档为准。
- 升级前导出或复制旧配置，并记录原内核版本。
- 打开当前版本的 DNS、DNS Server、DNS Rule、Dial Fields 和 TUN 文档，逐项核对弃用字段。
- 先运行 check，再启动；不要把“能启动”当作“规则已按预期工作”。
- 先测试 local 或其他单一上游，再恢复 DoH/DoT、分流、FakeIP 和 TUN。
- 若升级后失败，回滚到备份配置和原内核版本，保存错误日志，再一次只迁移一个字段。
回滚原则：保留一份“最后可用配置”和一份“正在修改配置”，文件名明确区分；不要在没有备份的情况下使用 format 覆盖原文件，也不要把多个版本的字段混合拼接。
不同平台的最后检查点
- Windows：先确认系统代理、TUN 状态、网卡 DNS 和本地端口；PowerShell 的端口测试只能证明指定 TCP 端口的连通性。
- macOS：检查系统网络服务的 DNS、VPN/TUN 权限和是否存在其他网络扩展；官方文档特别提示，某些系统环境下 DNS 可能被系统代理和缓存影响。
- Android：确认 VPN 权限、应用是否被系统省电策略限制，以及 DNS 规则中使用的平台相关字段是否得到图形客户端支持。
- iOS：确认 VPN 配置授权、网络扩展状态和 Wi-Fi/蜂窝网络切换后的表现；不要把桌面端的端口占用判断直接套用到移动端。
每个平台都建议记录四项结果：配置 check 是否通过、节点域名能否解析、代理入口能否建立连接、开启 TUN 后系统 DNS 是否发生预期变化。四项中只有第一项通过时，问题仍处于配置或运行时连通性阶段。
常见问题
sing-box check 通过了，为什么网页还是打不开？
check 主要用于发现配置结构、JSON 和字段引用问题，不能证明 DNS 上游、节点域名、TLS、端口或 TUN 路由可达。应继续用 nslookup 或 dig 测试域名，再单独测试节点端口和本地代理入口。
dns.rules 里的 server 和 dns.servers 里的 tag 不一致会怎样？
规则引用的是 DNS 服务器 tag。只要拼写、大小写或符号不一致，就可能出现找不到服务器或规则无法按预期执行。请逐字核对，并确认 dns.final 也引用了实际存在的 tag。
DoH 配置为什么需要 domain_resolver？
当 DoH 地址使用域名时，sing-box 需要先解析这个域名才能连接上游。domain_resolver 应使用一条已经可达且不会依赖自身的解析链路，否则可能出现循环依赖或启动后持续超时。
DNS 规则不生效，是不是一定要开启 FakeIP？
不是。应先检查规则顺序、server tag、final、上游可达性和 TUN 接管。只有日志或应用行为明确指向地址映射、FakeIP 或 TUN DNS 劫持时，才进入 FakeIP 专项排查。
升级 sing-box 后旧 DNS 配置报错怎么办？
保留旧配置和旧内核版本，先运行当前构建的 check，再对照官方 DNS、DNS Server、DNS Rule 和 Dial Fields 文档迁移字段。一次只改一个字段，校验和启动都通过后再恢复其他规则。