sing-box DNS 配置教程：可复制 JSON、分流规则与 TUN 排查
简答：先用一个 DNS Server 加 final 验证基础解析，再按场景加入 DoH、域名规则和 TUN。配置失败时依次检查 server tag、规则顺序、DNS 出口、route.auto_detect_interface，以及 TUN 是否重复劫持 53 端口。
定义：sing-box DNS 是由 DNS Server、DNS Rule、final、strategy 和路由出口共同组成的解析模块，用来决定查询匹配什么规则、交给哪个 DNS 服务器以及通过哪条连接路径发出。
三步速查：先复制最小配置，再逐层启用功能
本文是 acaisbest.shop 的第三方使用指南，不代表 sing-box 官方。配置字段以当前核心版本和客户端封装为准；截至 2026-10-27，官方文档将新式 DNS Server 结构定义为带有 type 与 tag 的服务器对象。
| 步骤 | 先做什么 | 通过标准 |
|---|---|---|
| 1. 基础解析 | 只保留一个 local 或 HTTPS DNS Server，并让 final 指向它 | 配置能载入，普通域名可以解析 |
| 2. 加入分流 | 每次只加入一条 domain_suffix 规则，检查 action 与 server tag | 目标域名命中预期 DNS Server |
| 3. 开启 TUN | 再检查 dns_mode、auto_route 和默认网卡绑定 | TUN 开关前后均能解析，日志没有 timeout 或 loop |
最小可验证配置如下。它包含日志、DNS 和 direct 出口，适合先验证 JSON 结构与本地解析；它不是带 TUN、订阅或代理节点的完整上网配置。
{"log":{"level":"info"},"dns":{"servers":[{"type":"local","tag":"local"}],"final":"local","strategy":"prefer_ipv4"},"inbounds":[],"outbounds":[{"type":"direct","tag":"direct"}]}
官方 DNS 配置说明中，final 是默认 DNS Server tag；如果为空，官方文档说明会使用 servers 中的第一个服务器。基础结构可核对sing-box DNS 官方文档。
配置链路：DNS Server、Rule、route、detour 和 outbound 如何串起来
可以把一次查询拆成五个环节：应用发起域名查询 → sing-box 的 DNS Rule 检查条件 → DNS Rule Action 决定使用哪个 server → DNS Server 选择 UDP、TLS、HTTPS 或 local 等解析方式 → Dial Fields、detour 或默认出口建立连接。解析结果返回后，route 再决定应用的实际流量交给哪个 outbound。
| 对象 | 作用 | 常见误区 |
|---|---|---|
dns.servers | 定义可用 DNS 服务器及 tag | 把服务器地址写成旧版 Legacy 格式，或引用不存在的 tag |
dns.rules | 按域名、网络、查询类型等条件匹配请求 | 规则顺序过宽，前一条规则先结束匹配 |
action: route | 将命中的查询交给指定 server | 只写匹配条件，不写 action |
detour 或 Dial Fields | 决定 DNS Server 连接如何拨出 | 误以为 DNS server tag 就等于代理 outbound |
route | 决定普通流量、DNS 劫持和默认网卡路径 | 只改 DNS，不处理 TUN 下的路由回环 |
outbound | 实际承载 direct、代理或 block 等连接 | 把已废弃的 DNS outbound 当成新配置的必需项 |
DNS Rule Action 官方页面把 route、server、timeout、缓存和客户端子网等处理字段单独列出；应优先按DNS Rule Action 官方文档核对，而不是沿用旧教程中的字段位置。
需要区分两条路径：DNS 查询路径决定“域名如何解析”，普通流量路径决定“应用连接解析出的 IP 时走哪个 outbound”。DNS Server 的连接可以使用独立的 Dial Fields；它不代表普通应用流量自动改走同一个 outbound。
三份可复制配置：本地解析、DoH 与域名分流
场景一：本地系统或局域网解析
适合先验证系统 DNS、局域网域名或公司内网解析。新式 local Server 使用 type 和 tag；官方说明当前新式 local 能处理所有查询类型，但 Android 图形客户端仍会通过平台接口获取上游 DNS，macOS 也存在平台网络扩展相关行为，因此跨平台结果要以客户端实际核心为准。可核对Local DNS Server 官方文档。
{"log":{"level":"info"},"dns":{"servers":[{"type":"local","tag":"local","prefer_go":false}],"final":"local","strategy":"prefer_ipv4"},"inbounds":[],"outbounds":[{"type":"direct","tag":"direct"}]}
prefer_go 不要默认打开。官方说明它会改变 local DNS 尽可能自行拨号解析的行为；Android 图形客户端和 macOS 网络扩展存在例外或平台限制。只有在确认当前平台需要该行为时再改动。
场景二：使用 HTTPS DNS
下面示例使用 Cloudflare 官方公开的 DoH 地址，仅用于演示新式 HTTPS Server 结构。Cloudflare 官方资料给出的 DoH 端点为 https://cloudflare-dns.com/dns-query；sing-box 的 HTTPS Server 结构要求填写 server，路径默认为 /dns-query，使用域名时还要解决 DNS Server 自身的域名解析问题。相关字段见sing-box HTTPS DNS Server 文档，端点见Cloudflare DoH 官方说明。
{"log":{"level":"info"},"dns":{"servers":[{"type":"https","tag":"cloudflare","server":"cloudflare-dns.com","server_port":443,"path":"/dns-query"}],"final":"cloudflare","strategy":"prefer_ipv4"},"inbounds":[],"outbounds":[{"type":"direct","tag":"direct"}]}
这是结构完整的 DNS 测试配置，但是否能直接启动还取决于当前核心对 HTTPS Server 域名解析的默认处理和客户端封装。若日志提示无法解析 cloudflare-dns.com，先改用 local 作为引导解析，或按当前版本的 Dial Fields 配置 domain_resolver，不要把错误归因于 DoH 本身。
场景三：局域网后缀走 local，其余查询走 HTTPS
下面配置用于演示域名后缀分流。lan 只是局域网后缀示例；如果你的网络使用 home.arpa、公司内部后缀或其他实际域名，应替换为真实后缀。Cloudflare DoH 端点由上面的官方资料支持。
{"log":{"level":"info"},"dns":{"servers":[{"type":"local","tag":"local"},{"type":"https","tag":"cloudflare","server":"cloudflare-dns.com","server_port":443,"path":"/dns-query"}],"rules":[{"domain_suffix":["lan"],"action":"route","server":"local"}],"final":"cloudflare","strategy":"prefer_ipv4"},"inbounds":[],"outbounds":[{"type":"direct","tag":"direct"}]}
- 先把
lan替换成你实际使用的内网后缀。 - 确认
local和cloudflare两个 tag 都存在。 - 确认
action为route，且server指向正确 tag。 - 先测试一个局域网域名，再测试一个普通公网域名。
- 如果公网域名超时，临时把
final改为local，判断问题来自 DoH 连接还是规则。
UDP、TCP、TLS、HTTPS、QUIC、HTTP/3 怎么选
| 类型 | 优先考虑的场景 | 隐私与兼容性判断 | 配置重点 |
|---|---|---|---|
udp | 局域网或基础连通性测试 | 传统明文 DNS，部署简单，但查询内容未加密 | 服务器地址、端口和出口路径 |
tcp | UDP 不稳定或需要 TCP DNS | 仍不是加密传输，兼容性通常较好 | 服务器地址、端口和连接超时 |
tls | 需要加密 DNS 且服务支持 DoT | TLS 加密，通常使用 853 端口；要核对证书与服务器名称 | 服务器、端口、TLS 配置和域名校验 |
https | 需要将 DNS 放入 HTTPS 请求 | 通过 HTTPS 加密，通常走 443；还要处理 HTTPS Server 自身的域名解析 | server、path、TLS 与 domain resolver |
quic | 服务端明确提供 QUIC DNS | 加密并基于 QUIC，但中间网络和客户端支持需单独确认 | 服务端地址、端口、TLS 和出口 |
h3 | 服务端明确提供 HTTP/3 DoH | 使用 HTTP/3；不要因为 HTTPS 可用就推断 H3 一定可用 | HTTP/3 服务端、TLS、端口和域名解析 |
不要把“加密”直接等同于“更快”。UDP、TCP、TLS、HTTPS、QUIC 和 HTTP/3 的实际延迟取决于本地网络、解析器位置、连接复用、路由和客户端实现。选择顺序建议是：先选当前网络能稳定连通的类型，再确认是否需要加密，最后才比较 HTTPS、QUIC 或 HTTP/3 的链路表现。
Cloudflare 官方说明 DoH 使用 HTTPS 请求加密 DNS，DoT 使用 TLS 加密 DNS；Google 官方资料也将传统 UDP/TCP 与 DoH、DoT 分开说明。协议定义和服务端支持不能仅凭客户端字段名称推断，应以对应服务的官方参数为准：Cloudflare DoH 说明、Cloudflare DoT 说明、Google Secure Transports 说明。
TUN 下 DNS loop 与泄漏排查：先分清 DNS 劫持和普通路由
TUN 下不能只看 DNS Server。官方 TUN 文档将 dns_mode 分为 disabled、native 和 hijack：disabled 不配置原生 DNS，也不劫持 DNS；native 尽可能设置平台原生 DNS；hijack 在此基础上增加 53 端口劫持。dns_address 则指定 DNS 流量被处理的地址。字段和版本变化见sing-box TUN 官方文档。
- 备份配置。复制当前 JSON，保留一份可以正常启动的版本。
- 缩小 DNS。暂时只保留一个 DNS Server、一个
final，删除复杂 rules、FakeIP 和自定义缓存。 - 确认劫持层。检查系统 DNS、客户端 DNS、TUN
dns_mode是否同时接管 53 端口。 - 检查路由回环。启用
auto_route时，官方建议配置route.auto_detect_interface、route.default_interface或 outbound 的bind_interface，避免连接再次进入 TUN。 - Linux 单独检查。
auto_redirect仅支持 Linux 且要求启用auto_route；官方说明它通过 nftables 改善 TUN 路由，并建议 Linux 场景优先考虑。 - 逐项恢复。先恢复 rules，再恢复 TUN 劫持，最后恢复 FakeIP 或复杂路由，每次只加一项。
| 现象 | 日志或配置重点 | 回退动作 |
|---|---|---|
| 所有域名 timeout | DNS Server 连接、final、HTTPS Server 域名解析 | 改回 local，暂时关闭 TUN |
| 开启 TUN 后循环 | auto_route、默认网卡、outbound 绑定 | 关闭 auto_route 或加入接口检测后单独测试 |
| 部分域名解析异常 | rules 顺序、domain_suffix、server tag | 只保留一条明确规则 |
| 关闭 TUN 正常、开启后失败 | dns_mode、dns_address、53 端口劫持 | 先用 native 或关闭 hijack 对比 |
自查 DNS 泄漏时，不要只根据网页显示一个解析器名称下结论。分别记录 TUN 关闭和开启时的 DNS 日志、系统 DNS 设置、实际命中的 server tag，再使用站内的DNS 泄漏检查做对比；若结果不同，先判断是系统解析器、客户端劫持还是规则分流造成。
Windows、macOS、Linux、Android 的差异与操作顺序
| 平台 | 先检查 | 特别注意 |
|---|---|---|
| Windows | TUN 权限、系统代理、dns_mode、默认接口 | 官方 TUN 文档提到 strict_route 可影响 Windows 的多网卡 DNS 行为；修改后要测试虚拟网卡和本地应用。 |
| macOS | Network Extension 权限、local、TUN 与系统 DNS | 官方 local 文档说明 macOS 可能优先尝试 DHCP；reverse_mapping 也可能受系统代理和缓存影响。 |
| Linux | systemd-resolved、nftables、auto_route、auto_redirect | auto_redirect 需要 Linux、auto_route 和相应 nftables 能力；权限不足时会导致配置无法按预期生效。 |
| Android | VPN 权限、TUN 是否真正启用、平台 DNS | 官方说明 Android VPN 默认可能优先于 TUN；route.override_android_vpn 会影响是否把 VPN 作为上游网卡。 |
- 先在客户端界面确认实际使用的核心版本和当前配置文件。
- 备份配置后关闭 TUN，仅测试 DNS Server 和 final。
- 确认普通域名、局域网域名、IPv4 和 IPv6 的结果。
- 开启 TUN，记录
dns_mode、auto_route和默认接口相关日志。 - Linux 再检查 nftables；Android 再检查 VPN 权限和是否存在其他 VPN；macOS 再检查 Network Extension 权限。
平台差异不能通过一份桌面配置完全覆盖。尤其是 local、系统解析器和 TUN 的行为，取决于系统接口以及客户端是否使用图形客户端封装；遇到差异时应以当前客户端日志和对应平台官方说明为准。
版本迁移与撤销：1.12.0、1.14.0、1.15.0 重点检查什么
版本迁移前先备份旧配置，并确认客户端内置核心版本。官方 Migration 页面列出：1.12.0 引入新式 DNS Server 格式；旧 DNS Server 格式在 1.14.0 被移除；1.14.0 废弃 independent_cache，并新增 optimistic 与 DNS 查询超时；1.15.0 起 TUN 使用自有 TCP/IP 栈，旧的 stack 选项进入废弃流程。详情见sing-box Migration 官方文档和sing-box Deprecated 官方文档。
| 旧写法或字段 | 处理方式 | 验证方法 |
|---|---|---|
DNS Server 使用 address Legacy 结构 | 改为带 type、tag 的新式 Server | 逐个核对 Local、UDP、TLS、HTTPS 等对应页面 |
independent_cache | 删除，不要在新配置中继续依赖 | 启动日志不再出现废弃字段提示 |
store_rdrc | 按需求改为 store_dns，或先关闭缓存文件 | 重启后测试普通 DNS 与缓存行为 |
TUN stack | 1.15.0 起优先删除，使用新栈 | 重新测试路由、DNS 和本地应用 |
回滚方法是恢复备份文件，而不是把新旧字段混写。若升级后启动失败，先删除最近新增的 DNS Rule、缓存和 TUN 字段，回到“一台 server + 一个 final + direct outbound”，确认核心能启动后再逐项恢复。
完成标准：配置成功、规则命中、DNS 路径可解释
- JSON 可以载入，日志没有未知字段、server tag 不存在或 DNS Server 初始化失败。
final指向存在的 DNS Server tag，普通域名可以稳定解析。- 规则的域名条件与真实查询域名一致，命中后能看到预期的 server tag。
- 局域网后缀没有被错误交给远程 DNS，公网域名也不会因规则顺序被提前截断。
- 开启 TUN 后，DNS 请求不会反复回到自身，默认网卡和 outbound 路径能够解释。
- Windows、macOS、Linux、Android 分别完成权限、接口、VPN 或 nftables 检查。
- 升级后不再依赖官方标记为 deprecated 的 DNS 或 TUN 字段。
如果仍然失败，按“配置语法 → DNS Server → final → rules → TUN 劫持 → route 接口 → outbound”顺序回退。每次只恢复一层，才能确定问题究竟来自解析器、规则、路由还是平台封装。
常见问题
sing-box DNS 配置里的 final 是什么？
final 是默认 DNS Server tag。没有规则处理查询时使用它；官方文档说明留空时使用 servers 中的第一个服务器，仍应优先显式填写。可参考<a href="https://sing-box.sagernet.org/configuration/dns/">DNS 官方配置页</a>。
sing-box DNS 规则为什么不生效？
先检查规则顺序、domain_suffix 是否匹配真实域名、action 是否为 route，以及 server tag 是否与 servers 中的 tag 完全一致。
sing-box TUN 开启后 DNS 一直超时怎么办？
先保留一个 DNS Server 和 final，关闭复杂 rules，再检查 dns_mode、dns_address、auto_route 与默认接口，避免 DNS 请求被再次送回 TUN。
local 和旧版 Legacy DNS Server 有什么区别？
新式 local 使用 type 为 local 的服务器对象。官方说明新式 local 可处理所有查询类型，但 Android 和 macOS 存在平台行为差异，不要直接混用旧字段。
DoH、DoT 和 UDP 应该怎么选？
先选当前网络能稳定连接的类型；需要加密时再考虑 TLS 或 HTTPS。DoH 通常走 HTTPS，DoT 使用 TLS，具体服务器字段和证书要求要按对应官方文档填写。
independent_cache 还能继续使用吗？
官方已将 independent_cache 标记为 sing-box 1.14.0 废弃，并说明将在 1.16.0 移除。新配置建议删除该字段，缓存需求按当前 DNS 和 cache file 文档迁移。
怎样判断 sing-box DNS 是否泄漏？
分别记录 TUN 关闭与开启时的系统 DNS、sing-box 日志和命中的 server tag，再使用<a href="/guides/dns-leak-check/">DNS 泄漏检查</a>做对比；不要只根据单次网页结果判断。