sing-box DNS 配置：1.12/1.14+ 三套模板与 TUN 排障
简答：如果你只是想先让 sing-box 正常解析，先用模板一；需要按域名分流时使用模板二；只有在 1.14.0+ 且确认基础解析正常后，再使用模板三的 TUN DNS 劫持配置。先运行 sing-box check，再查看 DNS 日志，最后用 nslookup、dig 或系统 DNS 状态确认请求是否真的经过预期链路。
定义：sing-box DNS 配置，是在 JSON 中定义 DNS 上游 servers、按条件选择上游的 rules、未命中规则时使用的 final，并通过 TUN 或 route 规则决定实际 DNS 请求是否由 sing-box 接管。
先选模板：30 秒判断你该从哪里开始
本站是第三方使用指南站，不是 sing-box 或其他客户端的官网。本文只解决 sing-box DNS 配置，不讨论订阅价格或具体服务状态。
| 你的目标 | 先用哪套 | 适用版本 | 成功标准 |
|---|---|---|---|
| 确认 DNS 模块和基础配置能启动 | 模板一：基础解析 | 1.12.0+ 新格式；具体客户端封装需核实 | sing-box check 通过，日志无 DNS 初始化错误 |
| 让局域网域名与普通域名走不同上游 | 模板二：DNS 分流 | 优先 1.14.0+；1.12.0 使用前核对当前 schema | 固定域名查询时，日志显示命中了预期 DNS server |
| 让 TUN 接管端口 53 查询 | 模板三：TUN 劫持 | 1.14.0+；dns_mode 与 dns_address 的官方文档均标注自 1.14.0 起 | TUN 启动、hijack-dns 规则命中，且系统或应用没有绕过路径 |
官方 DNS 文档将 servers、rules、final 和 strategy 作为主要配置结构；官方 TUN 文档则明确标注 dns_mode 和 dns_address 自 1.14.0 起提供。查看 DNS 配置结构 查看 TUN 字段说明
- 先确认核心版本，不要只看图形客户端名称。
- 复制与版本匹配的模板，替换所有占位符。
- 运行
sing-box check -c config.json，再启动并查看日志。
版本矩阵：1.12.0 和 1.14.0+ 不要混用字段
| 项目 | 1.12.0 | 1.14.0+ | 写配置时怎么做 |
|---|---|---|---|
| 新版 DNS server 结构 | 官方变更说明将 DNS server 重构列为 1.12.0 的变化；具体发行版封装需核实 | 应按新版 type、tag、server 等字段组织 | 优先使用新格式，旧配置迁移前先运行 check |
| 旧 DNS server 格式 | 兼容范围需结合实际核心版本和客户端封装核实 | 官方变更说明称旧格式兼容在 1.14.0 移除 | 不要把旧版 address 示例直接粘贴到 1.14.0+ |
domain_resolver | 新 Dial Fields 结构已出现，具体客户端支持需核实 | 域名形式的上游地址可使用 DNS server tag 字符串 | 例如 "bootstrap"，且该 tag 必须存在 |
dns_mode、dns_address | 不能默认认为可用 | 官方 TUN 文档标注自 1.14.0 起提供 | 1.12.0 不要直接套用模板三 |
independent_cache | 版本行为需核实 | 官方 DNS 文档标注 1.14.0 废弃，并计划在 1.16.0 移除 | 新配置不要加入该字段 |
官方变更日志说明：1.12.0 重构 DNS server，并计划在 1.14.0 移除旧格式兼容；官方 DNS 页面还标注 independent_cache 在 1.14.0 废弃、预计 1.16.0 移除。由于不同图形客户端可能捆绑不同核心，最终以客户端显示的核心版本和当前 schema 为准。查看官方 Change Log 查看官方 Dial Fields
模板一：基础解析配置，先确认 DNS 模块能工作
这套模板不启用 TUN、不依赖 DoH 域名，也不需要代理出站，适合先验证 JSON 结构和本地 DNS。它使用 1.12.0+ 新格式；如果你的 1.12.0 客户端拒绝 type 结构，请不要反复修改，先核对实际核心版本与迁移说明。
可直接校验：不含外部服务商占位符。需要按环境修改：listen_port 若已被占用，应改为其他未使用端口。
{"log":{"level":"info"},"dns":{"servers":[{"type":"local","tag":"local"}],"final":"local","strategy":"prefer_ipv4"},"inbounds":[{"type":"mixed","tag":"mixed-in","listen":"127.0.0.1","listen_port":2080}],"outbounds":[{"type":"direct","tag":"direct"}],"route":{"final":"direct"}}
- 保存为
config.json。 - 在运行 sing-box 的终端执行
sing-box check -c config.json。 - 启动后，将测试应用临时指向
127.0.0.1:2080，再查询一个固定域名。 - 确认日志没有 DNS 初始化失败，再进入模板二或模板三。
官方配置文档提供了 JSON 配置结构以及 check、format 等命令；图形客户端若不提供命令行入口，则使用客户端自己的配置检查功能。查看官方配置与检查命令
模板二：标准 DNS 分流，区分局域网与远程上游
这套模板把局域网后缀交给 local，其余查询交给 HTTPS DNS。它不能直接运行，必须替换 your-doh.example，并确认 proxy-out 指向真实存在的 SOCKS 出站；如果暂时没有代理出站，可把 DNS server 的 detour 删除，并把 route 的 final 改为 direct 做基础对照。
{"log":{"level":"info"},"dns":{"servers":[{"type":"local","tag":"local"},{"type":"udp","tag":"bootstrap","server":"1.1.1.1","server_port":53},{"type":"https","tag":"remote-dns","server":"your-doh.example","server_port":443,"path":"/dns-query","domain_resolver":"bootstrap","detour":"proxy-out"}],"rules":[{"domain_suffix":[".lan",".local"],"action":"route","server":"local"},{"domain":["router.lan"],"action":"route","server":"local"},{"action":"route","server":"remote-dns"}],"final":"remote-dns","strategy":"prefer_ipv4"},"inbounds":[{"type":"mixed","tag":"mixed-in","listen":"127.0.0.1","listen_port":2080}],"outbounds":[{"type":"direct","tag":"direct"},{"type":"socks","tag":"proxy-out","server":"127.0.0.1","server_port":1080}],"route":{"final":"direct"}}
这里有三个容易混淆的字段：domain_resolver 用于解析 DoH 服务器自身的域名；detour 决定连接该上游时使用的出站；DNS 的 final 决定没有命中 DNS 规则时使用哪个 DNS server。它们不是同一个层级。
官方 DoH 文档要求：如果 server 使用域名，就需要设置 domain_resolver；官方 Dial Fields 文档说明该字段可以直接填写 DNS server tag 字符串。DNS 规则中的 route action 则要求填写目标 DNS server 的 tag。查看官方 DoH 字段 查看官方 domain_resolver 查看官方 DNS route action
模板三：1.14.0+ TUN DNS 劫持，先用直连版验证
这套模板只适用于已经确认基础解析正常、且实际核心为 1.14.0+ 的场景。为避免把代理链路问题误判为 DNS 问题，下面使用 direct 作为默认出站；如果你确实需要代理出站，再把 route.final 替换为现有且已验证的出站 tag。不要把 proxy-out 当作必然存在的字段。
可直接校验：字段结构不依赖具体 DoH 服务。平台相关：172.18.0.1/30 与 172.18.0.2 只是示例组合，不是所有客户端、系统或网络环境的固定值；地址冲突、权限和图形客户端封装仍需核实。
{"log":{"level":"info"},"dns":{"servers":[{"type":"local","tag":"local"}],"final":"local","strategy":"prefer_ipv4"},"inbounds":[{"type":"tun","tag":"tun-in","interface_name":"sing-box-tun","address":["172.18.0.1/30"],"auto_route":true,"strict_route":true,"dns_mode":"hijack","dns_address":["172.18.0.2"]}],"outbounds":[{"type":"direct","tag":"direct"}],"route":{"auto_detect_interface":true,"rules":[{"action":"hijack-dns"}],"final":"direct"}}
- 先确认核心版本为 1.14.0 或更高，并确认系统允许创建 TUN。
- 运行
sing-box check -c config.json。 - 启动后观察是否出现 TUN 权限、地址冲突或路由错误。
- 确认 DNS 查询日志出现，再做系统级泄漏检查。
官方 TUN 文档说明，dns_mode 的 hijack 模式会额外处理端口 53 劫持；显式设置 dns_address 时，需要配置处理这些地址的 hijack-dns 路由规则。官方 route action 文档将 hijack-dns 定义为把 DNS 请求交给 sing-box DNS 模块。查看官方 TUN dns_mode 与 dns_address 查看官方 hijack-dns action
DNS 请求链路：从应用到上游再返回
可以按下面的顺序理解一次请求，排错时也按这个顺序逐段验证：
- 应用发起查询：浏览器、系统组件或应用自己的 DNS 模块请求域名。
- TUN 或系统代理接管：如果启用 TUN，符合路由条件的流量进入 sing-box；没有 TUN 时，应用可能直接使用系统 DNS。
- hijack-dns 处理：命中 route 规则的
action: hijack-dns后，请求进入 sing-box DNS 模块。 - DNS rules 匹配：按域名、后缀等条件选择
action: route的目标 server。 - 上游 server 查询：
local、udp、https等 server 类型负责执行查询。 - domain_resolver 与 detour：如果上游地址是域名，
domain_resolver解析该域名；detour决定连接上游时使用的出站。 - 返回应用：DNS 响应回到应用；普通连接的最终出站仍由 route 规则决定。
因此，看到端口 53 在监听、TUN 图标出现或客户端显示节点在线，都不能单独证明 DNS 没有绕过。至少要同时看配置检查结果、日志、系统 DNS 状态和实际请求路径。
防 DNS 泄漏验证：不要只用一次 nslookup 判断
“防泄漏”不是单次查询成功，而是确认不同请求入口没有绕过预期链路。下面采用固定域名、一次只改一个变量的方式。
| 平台 | 先检查什么 | 操作 | 如何判断 |
|---|---|---|---|
| Windows | 系统 DNS、系统代理、TUN 和浏览器安全 DNS | 运行 nslookup example.com；再查看系统网络适配器 DNS，并检查浏览器是否单独启用了 Secure DNS | 如果浏览器单独发起 HTTPS DNS，系统代理或 TUN 的端口 53 规则可能无法覆盖它；应临时关闭浏览器独立 DNS 做对照，测试后恢复 |
| Android | 系统 VPN、应用代理、浏览器自带 DNS | 先只启用 sing-box TUN，关闭其他 VPN；分别测试浏览器和一个普通应用 | 两类应用结果不一致时，优先检查应用自身 DNS 或 VPN 接管，而不是立即更换上游 |
| Linux | systemd-resolved、TUN 路由和实际 53 端口流量 | 查看 resolvectl status；用 dig example.com 测试；必要时使用 sudo tcpdump -ni any port 53 观察是否有绕过接口的明文 DNS 流量 | 如果仍有系统接口直接发出 53 流量，检查 TUN、DNS 服务和 route 规则 |
| OpenWrt | fw4、auto_redirect、dnsmasq 和路由器自身 DNS | 确认 Linux TUN 使用 auto_route；按官方说明检查 auto_redirect 与 fw4；再分别测试路由器本机和 LAN 客户端 | 本机正常、LAN 客户端异常时，检查转发、dnsmasq 监听地址和防火墙规则，不要只看 sing-box 进程是否运行 |
官方 TUN 文档说明，Linux 上 auto_redirect 依赖 auto_route，并会自动插入 OpenWrt fw4 兼容规则；但平台内核、权限、dnsmasq 和现有防火墙配置仍可能改变结果。查看官方 auto_redirect 与 OpenWrt 说明
验证时建议分别记录四项：系统 DNS 地址、浏览器或应用是否自带 DNS、sing-box 日志是否出现对应查询、抓包或系统状态中是否仍有直连 DNS。任何一项不一致，都只能说明“还有一条路径未确认”，不能直接断言配置一定泄漏或一定安全。
常见故障速查：现象、优先动作与验证方式
| 现象或提示 | 通常的排查方向 | 优先动作 | 验证方式 |
|---|---|---|---|
| 字段未知、配置无法启动 | 版本不匹配、旧字段或拼写错误 | 确认核心版本，删除新旧混用字段 | 重新运行 sing-box check，一次只改一个字段 |
| 找不到 DNS server tag | rules 或 final 引用了不存在的 tag | 逐字核对 local、bootstrap、remote-dns | 检查每个引用是否都能在 servers 找到 |
| DoH 域名解析失败 | domain_resolver 缺失、tag 错误或 bootstrap 不可用 | 先换回模板一的 local，再单独测试 bootstrap | 查看日志是否在 HTTPS 建连前已经失败 |
| timeout | 上游不可达、detour、TLS 或路由路径异常 | 固定域名，依次测试 local、UDP、DoH | 每次只改变一个上游或出站，比较日志 |
| permission denied | TUN、路由或系统 DNS 设置缺少权限 | 按平台要求以适当权限启动，不要关闭安全校验 | 确认提升权限后是否仍为同一错误 |
| 连接拒绝 | 本地 SOCKS 端口没有服务或端口写错 | 检查端口监听和对应应用，不要把监听存在当作链路可用 | 用固定请求测试实际返回 |
| check 通过但打不开网页 | 上游、出站、TLS、系统代理或应用 DNS 仍未验证 | 回到模板一，先分离 DNS 与代理链路 | 分别测试 DNS 响应、代理连接和实际页面 |
FakeIP 要不要开：先解决普通解析，再考虑映射
FakeIP 不是普通 DNS 分流或 TUN 劫持的必需组件。官方 DNS server 文档将 fakeip 列为独立的 server 类型，适合已经明确需要地址映射和相关规则配合的场景。
如果你的问题只是“域名解析失败”，先使用 local、udp 或 https 验证基础链路，不要同时加入 FakeIP。只有在确认某个应用、规则或透明代理流程需要 FakeIP 后，再单独加入对应 server，并记录启用前后的域名解析结果、应用兼容性和关闭后的回退表现。查看官方 DNS server 类型 查看官方 FakeIP 字段
FAQ：sing-box DNS 配置常见问题
sing-box 1.12.0 能不能直接使用本文模板？
模板一采用官方 1.12.0 起出现的新 DNS server 结构，但不同客户端可能捆绑不同核心或限制字段，因此应先查看实际核心版本并运行 check。模板三使用的 dns_mode 和 dns_address 不要默认用于 1.12.0；官方 TUN 页面将它们标注为自 1.14.0 起提供。
1.14.0+ 还能直接照抄旧版 address 配置吗？
不应这样做。官方变更日志说明 DNS server 在 1.12.0 重构，旧格式兼容在 1.14.0 移除。应按当前 DNS server 页面使用 type、tag、server 等字段。
domain_resolver 应该写对象还是字符串？
当前 Dial Fields 文档说明，直接写 DNS server tag 字符串等价于设置该选项中的 server，例如 "bootstrap"。该 tag 必须在 DNS servers 中存在；不要使用没有 schema 依据的对象写法。
dns_address 一定要写 172.18.0.2 吗？
不一定。官方只规定它是供 dns_mode 使用的 DNS server 地址列表；显式设置后要配置对应的 hijack-dns 规则。172.18.0.1/30 与 172.18.0.2 是本文示例组合，是否适合你的系统和客户端需核实。
为什么 TUN 已启动，DNS 仍可能绕过？
TUN 启动只说明接口或 VPN 通道建立，不代表浏览器自带 DoH、系统 DNS、其他 VPN 或应用代理都已纳入同一链路。请按系统 DNS、应用 DNS、sing-box 日志和实际 53 流量四项分别验证。
FakeIP 是防 DNS 泄漏的必需项吗？
不是。FakeIP 是独立的 DNS server 类型，只在确实需要地址映射的场景启用。普通 DNS 分流可以先使用 local、UDP 或 HTTPS 上游。
没有 proxy-out，模板二和模板三怎么办？
模板二应删除对不存在出站的 detour，并用已验证的出站替代；模板三先使用 direct 做 TUN 与 DNS 对照测试，确认基础链路后再接入现有出站。不要凭空填写一个 tag。
常见问题
sing-box 1.12.0 能不能直接使用本文模板？
模板一采用 1.12.0 起出现的新 DNS server 结构，但客户端捆绑核心和字段限制需核实。模板三的 dns_mode、dns_address 不要默认用于 1.12.0。
1.14.0+ 还能使用旧版 address 配置吗？
不应直接照抄。官方变更日志说明 DNS server 在 1.12.0 重构，旧格式兼容在 1.14.0 移除。
domain_resolver 应该写什么？
当前 Dial Fields 文档支持直接写 DNS server tag 字符串，例如 "bootstrap"，且该 tag 必须存在于 DNS servers 中。
dns_address 是否必须使用 172.18.0.2？
不是。它只是本文与 172.18.0.1/30 配套的示例地址，实际组合需结合当前核心、客户端和平台核实。
FakeIP 是防 DNS 泄漏的必需项吗？
不是。FakeIP 是独立的 DNS server 类型，只有在明确需要地址映射时才建议单独启用。
没有 proxy-out 时如何测试？
模板二删除不存在的 detour 并替换为已验证出站；模板三先用 direct 验证 TUN 与 DNS，再接入真实出站。