knotic

sing-box 怎么设置 DNS？从最小配置到 TUN 模式排查

更新于 2026-10-31 · knotic.store

简答：sing-box 设置 DNS，核心是配置 dns.servers、dns.rules 和 final：先添加 DNS 服务器，再用 rules 按域名分流，最后用 final 指定默认服务器。普通代理只需配置 DNS 模块；TUN 模式还要检查 dns_mode、dns_address 与 hijack-dns，浏览器能打开并不等于 DNS 请求已经按预期经过 sing-box。

定义：sing-box 的 DNS 配置是由 DNS 服务器列表、匹配规则和默认服务器共同组成的解析链路，TUN 模式还可通过 dns_mode 与 hijack-dns 接管系统 DNS 请求。

先试这一步：最小 DNS 配置与字段对照

适用范围：sing-box 1.14 及以上配置结构；适用于命令行配置和能够编辑 JSON 的图形客户端。本文不覆盖某个图形客户端的具体菜单名称，也不提供未经核实的第三方配置模板。

先备份原配置，只修改 dns 部分，然后运行配置检查。sing-box 官方配置文档明确使用 JSON，并提供 sing-box check 检查命令。查看官方配置检查说明 sing-box.sagernet.org

字段作用先怎么填验证边界
servers定义可用的 DNS 服务器先使用一个 local 或已核实地址的 UDP、TLS、HTTPS 服务器服务器被识别，不代表查询一定成功
rules按域名、后缀、网络等条件选择服务器先写一条明确的 domain_suffix 规则规则命中还要结合日志或实际解析结果验证
final指定没有命中前面规则时使用的服务器填已存在的服务器标签标签写错会导致配置检查或运行失败
strategy控制默认解析地址策略不确定时先不写，或使用官方支持的值只影响解析策略，不等于改变 DNS 服务器

最小示例：

{"dns":{"servers":[{"type":"local","tag":"local"}],"final":"local"}}

local 是 sing-box 的新式本地 DNS 服务器类型；官方文档说明，新式服务器结构从 1.12.0 起使用，旧的 legacy DNS 服务器配置已在 1.14.0 移除。查看 DNS Server 结构 查看旧配置迁移说明 sing-box.sagernet.org

  1. 复制配置文件作为备份。
  2. 把上面的 dns 对象合并到现有配置，不要删除已有的 inbounds、outbounds 和 route。
  3. 运行 sing-box check。
  4. 检查通过后再启动或重载 sing-box。

停止条件：如果检查报 unknown field、JSON 语法错误或服务器标签不存在，先不要继续改 TUN；先按报错字段回滚并修复。

添加 UDP、TLS 或 HTTPS DNS 服务器

DNS 服务器类型要与服务端实际协议一致。官方文档列出了 local、udp、tls、https、h3、fakeip 等类型；本文只展示结构，不替读者指定某个服务商或承诺可用性。官方 DNS Server 类型列表 sing-box.sagernet.org

UDP 示例：

{"dns":{"servers":[{"type":"udp","tag":"udp-dns","server":"你的DNS服务器IP","server_port":53}],"final":"udp-dns"}}

UDP 服务器的 server 是必填项，端口默认是 53。如果填写域名而不是 IP，还要设置 domain_resolver，否则 sing-box 没有明确的解析器来解析这个服务器域名。查看 UDP DNS 字段 查看 domain_resolver 说明 sing-box.sagernet.org

TLS 和 HTTPS 服务器的结构分别如下：

  • tls 通常使用 server、server_port 和 tls 对象；默认端口为 853。
  • https 使用 server、server_port、path、headers 和 tls；默认端口为 443，默认路径为 /dns-query。

如果服务端地址是域名，继续检查 domain_resolver；如果希望 DNS 请求通过某个出站连接，则检查拨号字段中的 detour。官方文档说明，设置 detour 后，其他拨号字段会被忽略，因此不要同时堆叠互相冲突的连接参数。查看 DoT 配置 查看 DoH 配置 查看 detour 与 domain_resolver sing-box.sagernet.org

验证边界：配置检查通过只能说明字段和结构基本可识别，不能证明上游 DNS 可达，也不能证明所有域名都能解析。应继续观察运行日志，并用实际域名进行查询测试。

用 rules 和 final 做 DNS 分流

rules 用来匹配 DNS 查询，final 用来处理没有命中前面规则的查询。新版本 DNS 规则要求使用 action，服务器选择放在规则动作中；旧版直接写 server 的方式已经废弃。查看官方 DNS 规则文档 sing-box.sagernet.org

一个可读性较好的分流骨架如下。示例中的服务器地址和标签必须替换为你已经配置并核实可用的服务器：

{"dns":{"servers":[{"type":"local","tag":"local"},{"type":"udp","tag":"remote-dns","server":"你的DNS服务器IP","server_port":53}],"rules":[{"domain_suffix":[".example.local"],"action":{"action":"route","server":"local"}},{"domain_suffix":[".example.net"],"action":{"action":"route","server":"remote-dns"}}],"final":"local"}}

阅读顺序是：先看查询是否匹配第一条后缀规则；命中后执行对应的 route 动作；没有命中时使用 final。官方文档支持按完整域名、域名后缀、关键词、正则、规则集等条件匹配。查看可用匹配条件 sing-box.sagernet.org

目标配置思路常见错误
所有查询使用同一个 DNS只配置一个服务器，并把它写入 finalfinal 拼写与服务器 tag 不一致
内网域名使用本地解析用 domain_suffix 匹配内网后缀，动作路由到 local把后缀写成完整域名，导致其他主机名不匹配
部分域名使用另一台 DNS增加明确的 domain 或 domain_suffix 规则规则顺序过于宽泛，提前匹配了后续规则

停止条件：如果某个域名解析结果不符合预期，不要先增加更多规则。先确认日志中的查询域名、命中的规则和最终使用的服务器；如果无法看到这些信息，就只能把问题标记为“未核实”，不要把浏览器打开或打不开直接当作分流成功或失败。

TUN 模式：dns_mode、dns_address 与 hijack-dns 怎么配合

普通 HTTP、SOCKS 或混合代理模式下，DNS 模块是否接管系统查询取决于客户端和系统代理行为；启用 TUN 后，还要看 TUN 入站的 DNS 处理方式。官方文档显示，dns_mode 自 sing-box 1.14.0 起可用：disabled 不设置原生 DNS 也不劫持，native 尽可能设置平台原生接口 DNS，hijack 在此基础上增加 53 端口劫持。启用 auto_route 时，默认模式是 hijack。查看 TUN DNS 模式 sing-box.sagernet.org

TUN 配置可以先从下面的结构理解：

{"inbounds":[{"type":"tun","tag":"tun-in","address":["172.18.0.1/30"],"auto_route":true,"dns_mode":"hijack","dns_address":["172.18.0.2"]}]}

dns_address 是 TUN DNS 模式使用的地址列表。官方说明指出，手动设置 dns_address 后，应配置对应的 hijack-dns 路由规则来处理发往这些地址的 DNS 流量。查看 dns_address 说明 查看 hijack-dns 动作 sing-box.sagernet.org

路由动作的最小结构是：

{"route":{"rules":[{"inbound":["tun-in"],"action":{"action":"hijack-dns"}}]}}

这条规则的作用是把匹配到的 DNS 请求交给 sing-box DNS 模块，而不是简单地把请求发往某个固定服务器。启用 TUN 后还要检查 auto_route 是否真的接管流量，并避免 sing-box 自己的 DNS 请求再次被 TUN 劫回形成循环。官方 TUN 文档建议通过 route.auto_detect_interface、route.default_interface 或出站的 bind_interface 避免流量环回。查看 auto_route 环回说明 sing-box.sagernet.org

Windows 场景还要注意 strict_route：官方文档说明，它可阻止普通多宿主 DNS 解析行为造成的 DNS 泄漏，但也可能影响部分依赖特殊网络接口的程序。因此，启用后如果某个虚拟机、容器或本地网络应用异常，应先记录现象，再临时回滚验证，而不是直接扩大路由范围。查看 strict_route 边界 sing-box.sagernet.org

FakeIP 要不要开？先区分解析与地址映射

FakeIP 不是普通 DNS 上游服务器的替代品，而是把域名映射到专用地址范围，再由 sing-box 根据映射关系处理连接。官方文档将 Fake IP 作为独立的 DNS Server 类型，并给出了 IPv4 与 IPv6 地址范围字段。查看 FakeIP 官方字段 sing-box.sagernet.org

  • 如果你的目标只是让域名能够解析，先不要启用 FakeIP，使用 local、UDP、TLS 或 HTTPS DNS 做基础验证。
  • 如果现有规则、客户端或应用明确依赖 FakeIP，再单独核对地址范围、回落规则和应用兼容性。
  • 如果启用 FakeIP 后只有部分应用打不开，先回滚到普通 DNS，确认问题是否来自 FakeIP，而不是直接修改所有路由规则。

停止条件：没有明确的 FakeIP 使用需求时，不要把它当作“DNS 设置必须项”。它会改变解析结果呈现方式，验证时应同时检查域名查询结果和后续连接是否能建立。

DNS 配置失败：按现象分流排查

  1. 配置文件无法加载：先运行 sing-box check。如果提示 unknown field，重点检查是否仍在使用旧版 servers、旧版规则字段或已迁移的 DNS 结构；不要用旧教程中的 legacy 字段直接覆盖新配置。
  2. 配置检查通过但域名无法解析：先把分流规则缩减为一个服务器和一个 final，再查看运行日志。若服务器地址使用域名，检查 domain_resolver；若使用 TUN，检查 DNS 请求是否被正确送到 sing-box。
  3. TUN 已连接但网页打不开：“TUN 已启动”只说明接口或路由建立，不能证明 DNS 查询和后续出站都成功。分别验证一个已知可解析域名、一个内网域名和一个实际访问目标。
  4. 解析出现循环或启动后网络中断：检查 DNS 上游请求是否再次经过同一个 TUN 劫持规则；设置 route.auto_detect_interface、route.default_interface 或正确的 bind_interface，并在修改前保留可回滚配置。
  5. Windows 出现 DNS 走其他网卡：检查 strict_route 和多网卡状态。启用严格路由可能改善 DNS 处理一致性，但也可能影响虚拟网络软件，验证时应逐项启用和回滚。

Linux 使用 systemd 服务时，官方安装文档提供了查看日志的命令：sudo journalctl -u sing-box --output cat -e，也可以使用 -f 实时跟踪。查看官方服务与日志命令 sing-box.sagernet.org

最短验证顺序是：配置检查通过 → sing-box 成功启动 → 日志没有 DNS 初始化错误 → 查询一个明确域名 → 再验证 TUN 或系统代理下的实际访问。单次查询成功不代表长期稳定，浏览器能打开也不代表所有应用都使用同一条 DNS 路径。

版本迁移提醒：不要继续照搬旧版 DNS 写法

如果你的配置来自较早教程，优先检查以下变化：

  • 旧 DNS 服务器配置已在 sing-box 1.14.0 移除，新的服务器使用 type 区分 local、udp、tls、https 等类型。
  • DNS 规则中的 server、disable_cache、rewrite_ttl 和 client_subnet 已移动到 DNS 规则动作，旧写法不要继续新增。
  • outbound 规则项已废弃并移除，分流时应按当前文档使用动作和服务器标签。
  • dns_mode、dns_address 属于 TUN 的新字段，不要把它们放到顶层 dns 对象中。
  • 官方文档显示，DNS 规则在 1.15.0 又增加了 dns_server_address 和 dns_search_domain 等匹配字段；如果当前版本不支持某字段，应以本机版本的 schema 和检查结果为准。

核验时间：2026-10-31。版本字段和废弃项可能继续变化，配置上线前应以 官方 DNS 文档、本机版本 schema 和 sing-box check 结果为准。 sing-box.sagernet.org

结论：先让单一 DNS 路径稳定，再增加分流和 TUN

如果你只是想让 sing-box 正常解析域名，先配置一个服务器并写入 final；如果要分流，再增加少量 domain_suffix 规则；如果要让 TUN 接管系统 DNS，再核对 dns_mode、dns_address、hijack-dns 和路由环回。每增加一层，都要先运行配置检查并观察日志。

边界云加速可作为跨境办公和多平台连接问题的线路排查入口，建议先明确设备、客户端、DNS 路径和实际故障现象，再决定是否需要进一步诊断。

常见问题

sing-box 的 DNS 配置写 servers 还是 server？

在当前 1.14+ 配置结构中，DNS 模块使用 servers 列表，每个服务器通过 type 和 tag 定义。旧版 legacy DNS 服务器配置已在 1.14.0 移除，不能继续照搬旧教程。

sing-box DNS 里的 final 是什么？

final 是默认 DNS 服务器标签。当查询没有命中前面的 rules 时，sing-box 使用 final 指定的服务器；如果没有填写，官方文档说明会使用第一个服务器。

TUN 模式一定要写 hijack-dns 吗？

不一定。是否需要显式写 hijack-dns，取决于 dns_mode、dns_address、auto_route、auto_redirect 以及具体平台。手动设置 dns_address 后，官方文档要求配置对应的 hijack-dns 路由规则来处理发往这些地址的 DNS 流量。

sing-box 配置检查通过但 DNS 仍然失败怎么办？

先确认上游服务器地址和端口可达，再查看运行日志，检查域名服务器是否需要 domain_resolver；如果使用 TUN，检查 DNS 请求是否被劫持到 sing-box，以及 sing-box 自己的上游请求是否发生路由循环。

FakeIP 是不是必须开启？

不是。只想完成普通域名解析时，先使用 local、UDP、TLS 或 HTTPS DNS 做基础配置。只有现有规则或应用明确需要 FakeIP 时，再单独启用并验证地址映射和连接兼容性。

相关阅读

参考资料

  1. sing-box 配置引言与 check 命令
  2. sing-box DNS 配置
  3. sing-box DNS Server 类型与结构
  4. sing-box UDP DNS Server
  5. sing-box DNS over TLS
  6. sing-box DNS over HTTPS
  7. sing-box DNS 规则
  8. sing-box TUN 与 dns_mode、dns_address
  9. sing-box hijack-dns 规则动作
  10. sing-box 拨号字段与 domain_resolver
  11. sing-box 旧版 DNS 配置迁移说明
  12. sing-box FakeIP DNS Server