快冲云

sing-box 怎么配置 DNS？从最小配置到分流排查

更新于 2026-10-27 · 1ck.shop

简答：先备份配置并确认 sing-box 核心版本，再从一个 local 或 HTTPS DNS 服务器开始。修改后用 sing-box check -c config.json 检查结构，重新载入并查看运行日志；check 通过不等于 DNS、TLS 或代理出站已经连通。

定义：sing-box 的 DNS 配置由 dns.servers 定义服务器，dns.rules 负责匹配查询并选择服务器，final 指定未命中规则时的默认服务器，detour 控制 DNS 连接使用的出站，domain_resolver 负责解析 DNS 服务器自身的域名。

三步速查：先解决 sing-box DNS 配置问题

本文是第三方使用指南，不代表任何客户端或服务的官方页面。若你只是想先让 DNS 工作，先不要同时加入 FakeIP、复杂规则和多个出站。

  1. 确认版本并备份：在客户端关于页面或命令行查看 sing-box 核心版本，复制现有 JSON 配置作为回滚文件。1.12.0 起 DNS 服务器采用新的 type、server 等结构，旧格式在后续版本中已移除，旧教程不能直接照抄。可查看官方变更说明：sing-box Change Log。
  2. 先用单服务器：优先配置一个 local 或 HTTPS DNS，并把 dns.final 指向已定义的服务器标签。
  3. 分开验证：先执行 sing-box check -c config.json 检查结构，再重新载入配置，通过日志确认 DNS 查询、TLS 握手和出站连接是否成功。官方配置文档同时列出了 check、format 和 merge 命令：sing-box 配置结构与命令。
你的需求优先写法先核对
先验证基础解析type: local系统或网络是否能正常解析
使用加密 DNStype: https主机名、TLS 名称和 domain_resolver
不同域名走不同 DNSdns.rules 加 action: route规则顺序和服务器标签
DNS 连接走代理DNS 服务器加入 detour代理出站标签是否真实存在

关键判断：check 主要检查配置结构，不能证明 DNS 主机、端口、TLS、代理出站或运行环境实际可达。不要把“校验通过”当成“DNS 已连通”。

三套常用配置片段：单 DNS、分流、DNS 走代理

下面都是需要合并到现有配置的 DNS 配置片段，不是包含节点、入站和凭据的完整生产配置。已有配置通常只替换或合并 dns 对象，避免重复覆盖 outbounds、route 和其他模块。

方案一：只使用系统 DNS

适合先排除规则、加密协议和代理出站因素：

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

local 会调用平台或系统提供的解析能力。Android、Apple、Linux 对系统解析器的使用方式存在平台差异，因此这一步只能作为基础链路验证，不代表所有平台行为完全相同。官方字段见 Local DNS Server。

方案二：按域名后缀分流

下面示例只演示“指定后缀走 local，其余查询走 DoH”，不代表所有后缀都能准确代表某个地区或网络类别：

{"dns":{"servers":[{"type":"local","tag":"local"},{"type":"https","tag":"doh","server":"cloudflare-dns.com","server_port":443,"path":"/dns-query","tls":{"server_name":"cloudflare-dns.com"},"domain_resolver":"local"}],"rules":[{"domain_suffix":["lan"],"action":"route","server":"local"}],"final":"doh","strategy":"prefer_ipv4"}}

规则中的 server 是 DNS 服务器标签，必须对应 dns.servers 中的 tag；它不是服务器地址。final 是未命中规则时使用的默认标签。官方 DNS 规则要求用 action: route 和 server 表达路由：DNS Rule。

为了覆盖域名本身及其子域，优先按当前官方规则说明确认 domain_suffix 的写法；带前导点的旧写法存在历史行为差异，不要从其他客户端的规则格式直接复制。

方案三：让 DoH 查询通过已有代理出站

如果现有配置中已经有一个标签为 proxy 的出站，可以把 DoH 服务器片段改为：

{"type":"https","tag":"doh-proxy","server":"cloudflare-dns.com","server_port":443,"path":"/dns-query","tls":{"server_name":"cloudflare-dns.com"},"detour":"proxy","domain_resolver":"local"}

这里的 proxy 只是示例标签，不是可直接使用的节点或凭据。你必须把它替换为现有配置中真实存在的出站标签；如果不存在，启动日志通常会出现找不到引用或连接失败。detour 控制 DNS 服务器连接使用的上游出站，而 domain_resolver 负责解析 cloudflare-dns.com。官方说明确认 HTTPS DNS 使用域名时需要设置 domain_resolver，并且新格式使用 Dial Fields：HTTPS DNS、Dial Fields。

不要把 DoH 的 server 通用地改成 IP 地址测试。即使网络能访问该 IP，TLS 证书名称或 SNI 仍可能不匹配；除非服务端明确支持该 IP 作为 TLS 访问名称。

dns.servers、rules、final、detour 怎么配合

可以把 sing-box DNS 查询链路简化为：先由 dns.rules 按域名、来源、网络或规则集匹配；命中后由 DNS 规则动作中的 server 选择服务器；没有命中时由 final 选择默认服务器；服务器建立连接时，再由 detour 选择出站。服务器标签、出站标签和服务器地址是三种不同概念。

字段作用常见错误
dns.servers[].tag给 DNS 服务器命名规则引用了不存在的标签
dns.rules[].action决定如何处理匹配到的查询把旧版顶层 server 写法与新格式混用
dns.rules[].server选择 DNS 服务器标签误写成 IP、域名或出站名称
dns.final未命中规则时的默认 DNS 服务器标签未在 servers 中定义
detour指定 DNS 连接使用的出站引用不存在的 outbounds[].tag
domain_resolver解析 DNS 服务器自身的域名DoH 主机名无法启动解析，或形成循环依赖

旧教程中的 DNS 规则顶层 server、旧版 DNS 服务器结构、旧版 outbound 规则和地址筛选字段都可能涉及迁移。官方迁移页建议将 DNS 服务器改为新结构，并用 Dial Fields 的 domain_resolver 替代旧的出站 DNS 规则：sing-box Migration。

UDP、DoT、DoH、DoQ、local 和 FakeIP 怎么选

类型适合先做什么注意事项
local验证系统 DNS 和基础网络结果受平台、系统和局域网解析器影响
udp使用传统 DNS 服务需要确认 UDP 端口和服务器地址可达
tls使用 DNS over TLS核对主机名、证书和 TLS 端口
https使用 DNS over HTTPS域名服务器应配 domain_resolver，TLS 名称要匹配
quic 或 h3明确需要 QUIC 或 HTTP/3 时还要确认 UDP 网络和服务端支持
fakeip明确采用 FakeIP 与 TUN 联动时不是普通 DNS 失败的默认修复方式

官方 DNS Server 列表包含 local、udp、tls、quic、https、h3 和 fakeip 等类型：DNS Server 类型列表。

FakeIP 只在明确需要时启用

FakeIP 是 DNS 服务器类型之一，需要在 dns.servers 中配置地址范围，例如官方文档展示的默认示例范围：

{"type":"fakeip","tag":"fakeip","inet4_range":"198.18.0.0/15","inet6_range":"2001:2::/48"}

它通常应与已经明确设计好的 TUN、路由和地址回查逻辑一起使用。若你只是遇到“域名解析失败”，先回到 local 或单个 HTTPS DNS，不要用 FakeIP 覆盖基础问题。启用前还要检查地址范围是否与局域网、企业网或其他隧道地址冲突。FakeIP 字段以官方页面为准：Fake IP。

配置校验、重新载入与失败分流

  1. 备份：先复制配置文件；如果要格式化，先确认备份路径。官方命令格式为 sing-box format -w -c config.json -D config_directory，不要在未备份时直接覆盖原文件。
  2. 结构校验：在配置文件所在环境执行 sing-box check -c config.json。如果客户端使用配置目录或额外参数，应按实际启动参数指定 -D、-C 或对应配置文件。
  3. 重新载入：在图形客户端中重新载入配置；系统服务则按自身服务管理方式重启。不要只修改磁盘文件后假定正在运行的进程已经读取新配置。
  4. 运行时验证：查看日志，确认是否出现 DNS 主机解析失败、TLS 握手失败、出站标签不存在、规则未命中、超时或 IPv6 连接异常。
  5. 撤销：停止客户端或服务，恢复备份配置，再重新载入。修复成功后再逐项加回规则、代理出口和 FakeIP。
现象优先检查处理方法
JSON 解析失败括号、逗号、字段层级、重复键恢复备份，逐段合并后重新执行指定文件的 check
DoH 启动失败server、TLS 名称、domain_resolver改用官方主机名并确保解析器标签存在
找不到 detouroutbounds[].tag改成真实出站标签，或暂时移除 detour 验证直连
规则不生效规则顺序、匹配字段、服务器标签先保留一条明确的 domain_suffix 规则测试
IPv6 连接异常strategy、系统 IPv6 和网络环境临时用 prefer_ipv4 对比，不要直接修改全部路由
Android 或 Apple 行为不同系统 DNS、客户端权限、TUN 是否接管先分别测试 local 和 HTTPS DNS，并查看客户端日志

Android 的 local DNS 可能始终通过平台接口获取上游解析器；Apple 和 Linux 也有各自的系统解析路径。遇到“桌面正常、移动端失败”，应先检查客户端权限、系统 VPN 或 TUN 状态，再判断 DNS 字段是否错误。官方 Local DNS 文档对这些平台差异有说明：Local DNS Server。

版本迁移：哪些旧字段不要继续照抄

版本不同是 sing-box DNS 教程最容易误导用户的地方。官方资料显示，1.12.0 重构了 DNS Server 格式，旧格式后来被移除；1.14.0 增加了 optimistic DNS cache、DNS 查询超时和响应匹配相关能力，同时将 independent_cache 标记为弃用并计划在 1.16.0 移除。新配置不要主动加入 independent_cache，旧配置则应按迁移文档清理。相关版本事实见 Change Log 和 Deprecated Feature List。

dns.timeout、规则动作中的 timeout、optimistic 和 match_response 都有版本前提。目标只是完成基础 DNS 配置时，不建议为了追新字段而加入这些高级能力；先确认核心版本，再对照对应官方文档逐项启用。

如果配置中同时出现旧版地址筛选字段、旧版规则顶层 server、independent_cache 或旧 DNS Server 结构，优先回退到最小配置并逐项迁移，不要一次性混合多个版本教程。

常见问题

sing-box 配置 DNS 后要执行什么命令？

使用指定文件执行 <code>sing-box check -c config.json</code>。它主要检查配置结构，不能证明 DNS 服务器、TLS 或代理出站实际可达。

DoH 的 domain_resolver 应该怎么写？

可以写成 DNS 服务器标签字符串，例如 <code>"domain_resolver":"local"</code>；也可以使用对应对象格式。官方 Dial Fields 说明字符串等价于设置对象中的 <code>server</code>。

HTTPS DNS 的 server 可以直接写 IP 吗？

不建议作为通用模板。使用域名时应配置 <code>domain_resolver</code>；直接写 IP 还可能遇到 TLS 证书名称或 SNI 不匹配。

dns.final 和 dns.rules 有什么区别？

<code>dns.rules</code>处理命中的查询，<code>final</code>是没有规则命中时使用的默认 DNS 服务器标签。规则里的 <code>server</code> 必须对应已定义的 DNS 标签。

为什么 sing-box check 通过但 DNS 仍然失败？

因为 check 主要验证配置结构。还要查看运行日志，排查域名解析、端口、TLS、detour 标签、规则顺序和实际网络可达性。

FakeIP 是不是 DNS 失败时的默认修复方法？

不是。FakeIP 更适合已经明确采用 TUN 和 FakeIP 路由的配置；普通 DNS 故障应先用 local 或单个 HTTPS DNS 验证基础链路。

相关阅读

参考资料

  1. sing-box 配置结构与 check、format、merge 命令
  2. sing-box DNS 全局字段说明
  3. sing-box DNS Server 类型列表
  4. sing-box Local DNS Server 官方说明
  5. sing-box HTTPS DNS 官方说明
  6. sing-box Fake IP 官方说明
  7. sing-box DNS Rule 官方说明
  8. sing-box Dial Fields 与 domain_resolver
  9. sing-box 官方迁移说明
  10. sing-box 官方 Change Log
  11. sing-box 官方 Deprecated Feature List