DNS — sing-box

sing-box 的 DNS 引擎是「带类型的服务器列表 + 结构化规则链」。每个 服务器都有 type 选择其传输方式（UDP、TLS、HTTPS、hosts 文件、 fake-ip 池、DHCP、systemd-resolved、Tailscale 内嵌）。规则使用与路由 规则相同的匹配字段集合，但带有 DNS 专用 action。

顶层选项

字段	类型	默认值	允许值	描述
servers	[]DNSServerOptions	[]	[DNSServerOptions]	DNS 服务器列表。每条目带 `type`（local、udp、tls、https、h3、dhcp、fakeip、hosts、resolved、tailscale）与对应的选项集合。
rules	[]DNSRule	[]	[DNSRule]	DNS 级别的路由规则。形态与路由规则相同，但携带 DNS 专用的 action 集合。
final	string	(unset)	<server tag>	无规则命中时使用的默认 DNS 服务器。为空时回退到 `servers[]` 中的第一个。
reverse_mapping	bool	false	true | false	维护反向映射（IP → 域名），使规则在连接的目标已解析为 IP 后仍能按原始域名匹配。

源码： option/dns.go:21-27 · 锚定版本 v1.13.11 (553cfa1)

以及内嵌的 DNSClientOptions：

字段	类型	默认值	允许值	描述
strategy	DomainStrategy	(prefer_ipv4)	prefer_ipv4 | prefer_ipv6 | ipv4_only | ipv6_only	默认地址家族偏好。
disable_cache	bool	false	true | false	禁用内存应答缓存。
disable_expire	bool	false	true | false	不按 TTL 淘汰缓存条目 —— 永久保留。
independent_cache	bool	false	true | false	为每个服务器 tag 使用独立缓存（而非全局共享）。
cache_capacity	uint32	(unbounded)	<int>	缓存条目最大数量。0 表示不设上限。
client_subnet	*badoption.Prefixable	(unset)	<CIDR>	出站查询中携带的 ECS（EDNS Client Subnet）。

源码： option/dns.go:105-112 · 锚定版本 v1.13.11 (553cfa1)

服务器类型

servers[] 中每条都有 type 字段。对应字段集合：

type: "local"

通过操作系统解析器解析（在 macOS / iOS 等系统解析器为权威路径的平台 上很实用）。提供 prefer_go 切到无 CGO 的 Go 解析器。

字段	类型	默认值	允许值	描述
prefer_go	bool	false	true | false	使用 Go 的 net.Resolver（无 CGO）代替平台原生解析器。原生解析器损坏或被限速时有用。

源码： option/dns.go:376-379 · 锚定版本 v1.13.11 (553cfa1)

type: "udp" 与 type: "tcp" —— RemoteDNSServerOptions

{ "type": "udp", "tag": "local-udp", "server": "8.8.8.8", "server_port": 53 }

字段	类型	默认值	允许值	描述
server	string	(required)	<host>	服务器主机名或 IP。
server_port	uint16	53 (udp/tcp), 853 (tls), 443 (https/h3)	<port>	服务器端口。

源码： option/dns.go:332-335 · 锚定版本 v1.13.11 (553cfa1)

type: "tls" —— DNS-over-TLS

字段同 udp / tcp 加上标准的 tls: 块。

type: "https" 与 type: "h3" —— DNS-over-HTTPS / -H3

字段	类型	默认值	允许值	描述
path	string	/dns-query	/<path>	DoH 端点路径。
method	string	POST	POST | GET	DoH 查询使用的 HTTP 方法。
headers	badoption.HTTPHeader	{}	{<header>: <value>}	附加 HTTP 头。

源码： option/dns.go:394-399 · 锚定版本 v1.13.11 (553cfa1)

type: "hosts" —— 本地 hosts 文件

字段	类型	默认值	允许值	描述
path	badoption.Listable[string]	[/etc/hosts]	[<file path>]	要合并的 hosts 文件路径列表。
predefined	*badjson.TypedMap[string, badoption.Listable[netip.Addr]]	{}	{<domain>: [<IP>]}	内联 hosts 表。优先级高于 `path`。

源码： option/dns.go:363-366 · 锚定版本 v1.13.11 (553cfa1)

type: "fakeip"

字段	类型	默认值	允许值	描述
inet4_range	*badoption.Prefix	(required for v4)	<CIDR>	为 IPv4 伪 IP 分配的 CIDR。
inet6_range	*badoption.Prefix	(required for v6)	<CIDR>	为 IPv6 伪 IP 分配的 CIDR。

源码： option/dns.go:401-404 · 锚定版本 v1.13.11 (553cfa1)

type: "dhcp"

字段	类型	默认值	允许值	描述
interface	string	(auto)	<interface>	使用其 DHCP 解析器的接口。

源码： option/dns.go:406-409 · 锚定版本 v1.13.11 (553cfa1)

其他类型

• type: "resolved" —— 读取 systemd-resolved 的每链路 nameserver （仅 Linux）。
• type: "tailscale" —— 使用 Tailscale 守护进程的 MagicDNS。
• type: "predefined" —— 返回硬编码的应答集合。
• type: "rcode" —— 返回固定 RCODE（NOERROR / NXDOMAIN / SERVFAIL 等）。

DNS 规则

DNS 规则使用与路由规则相同的多态 _Rule 形态（type: "default" 或 type: "logical"）和 RawDefaultDNSRule 中相同的 43 个匹配键。 差异在 action：

DNS action	含义
route（默认）	把查询送往 server: "<tag>"。可选字段：strategy、disable_cache、rewrite_ttl、client_subnet。
route-options	对后续规则匹配应用 DNS route 选项。
reject	丢弃查询。可配 method: "default"（NXDOMAIN）或 method: "drop"（无响应）。
predefined	返回硬编码答案（记录集合或 RCODE）。

示例

二服务器分流 —— 国内走本地 DoH，其余走 Cloudflare DoH：

{
  "dns": {
    "servers": [
      { "type": "https", "tag": "local",
        "server": "doh.pub", "path": "/dns-query" },
      { "type": "https", "tag": "remote",
        "server": "cloudflare-dns.com", "path": "/dns-query",
        "detour": "proxy" },
      { "type": "fakeip", "tag": "fakeip",
        "inet4_range": "198.18.0.0/15",
        "inet6_range": "fc00::/18" }
    ],
    "rules": [
      { "rule_set": ["geosite-cn"], "server": "local" },
      { "outbound": "any", "server": "remote" }
    ],
    "final": "remote",
    "strategy": "prefer_ipv4"
  }
}

通过 DNS 拦截广告：

{
  "dns": {
    "servers": [
      { "type": "https", "tag": "main",
        "server": "cloudflare-dns.com" }
    ],
    "rules": [
      {
        "domain_keyword": ["ads", "doubleclick", "googlesyndication"],
        "action": "reject",
        "method": "default"
      }
    ],
    "final": "main"
  }
}

说明

• 旧式顶层 fakeip: {...} 选项已 弃用 —— 请使用 type: "fakeip" 的服务器条目。sing-box 加载时会自动迁移旧配置， 但会打印弃用警告。
• reverse_mapping: true 让后续路由规则在嗅探已把目的解析为 IP 之 后仍能按域名匹配。在 fake-ip 与复杂域名规则共存时必备。
• independent_cache: true 适合存在「同一域名合法地返回不同答案」 的服务器（split-horizon 解析器）。
• DNS 规则与路由规则共享 相同 的匹配键词表，但发生在不同阶段： DNS 规则在解析查询上运行；路由规则在生成的连接上运行。
• type: "resolved" 通过 D-Bus 读取 systemd-resolved，仅在该解析器 确实在运行的 Linux 系统上有效。

跨内核说明

• Xray-core 使用扁平的 dns: 块，servers[] 元素是 URL 字符串 （或 NameServerConfig 对象）—— 没有 type 字段，URL scheme 决定 传输方式。参见 DNS — Xray-core。
• mihomo 提供 25 字段的 dns: 块，独立的 nameserver / fallback 列表与 nameserver-policy 映射。参见 DNS — mihomo。

源码： option/dns.go:21-409 · v1.13.11 (553cfa1)