sing-box DNS 设置方法：最小配置、分流、TUN 与 FakeIP
简答：sing-box 的 DNS 配置写在顶层 dns 对象中。最稳妥的顺序是：先用 local DNS 和 sing-box check 跑通，再添加 DNS 分流、DoH、TUN 或 FakeIP。若只改了 dns 但系统 DNS 没有进入 sing-box，还要检查 TUN 的 dns_mode、dns_address、权限和 hijack-dns 路由。
定义：sing-box DNS 是配置文件中的顶层 dns 模块，用于定义 DNS 上游、分流规则、默认服务器、解析策略、缓存以及 FakeIP 等行为。
先记住这 3 件事：配置位置、验证顺序和成功标准
本文是速飞云站内的第三方使用指南，不代表 sing-box 项目或任何服务商的官方页面。sing-box 使用 JSON 配置文件，dns、inbounds、outbounds 和 route 都属于顶层对象；已有配置时应合并对象，不要重复创建两个顶层 dns。官方配置总览
| 先做什么 | 判断标准 | 不通过时怎么回滚 |
|---|---|---|
只保留一个 local DNS 和明确的 final | 配置能通过检查，客户端可以启动 | 恢复修改前的配置备份 |
| 再增加一条 DNS 分流规则 | 规则命中域名能够解析，其他域名仍走 final | 删除最后增加的规则 |
| 最后测试 DoH、TUN 或 FakeIP | 启动日志没有 tag、权限或超时错误，普通域名和目标域名都能访问 | 关闭新增模块，只保留 local 配置 |
最短路径：备份配置→加入最小 dns→运行 sing-box check -c config.json→启动→测试一个普通域名→再逐项增加功能。官方配置页列出了 check、format 和 merge 命令。查看命令说明
最小完整配置：把 dns、inbounds、outbounds、route 放在一起
下面是一份用于理解结构的最小完整骨架，包含 TUN 入站、local DNS、direct 出站和 DNS 劫持规则。它不是任何服务商的订阅配置；如果你的客户端不支持 TUN、没有相应权限，或已有配置包含其他入站和出站，请先保留原文件并按对象合并。
{
"$schema": "https://sing-box.sagernet.org/schema.json",
"log": { "level": "info" },
"dns": {
"servers": [
{ "type": "local", "tag": "local" }
],
"final": "local",
"strategy": "prefer_ipv4"
},
"inbounds": [
{
"type": "tun",
"tag": "tun-in",
"address": ["172.18.0.1/30"],
"auto_route": true,
"dns_mode": "hijack"
}
],
"outbounds": [
{ "type": "direct", "tag": "direct" }
],
"route": {
"auto_detect_interface": true,
"rules": [
{ "action": "hijack-dns" }
],
"final": "direct"
}
}
必须核对的名称：dns.servers[].tag 定义 DNS 标签；dns.final 必须引用已有 DNS 标签；route.final 必须引用已有出站标签；detour、domain_resolver 和其他引用型字段也不能填写不存在的名称。hijack-dns 是官方路由动作，用于把 DNS 请求交给 sing-box DNS 模块。查看 hijack-dns 说明
已有配置的合并前后：如果原文件已有 inbounds、outbounds 和 route，通常只新增或修改顶层 dns，并把示例中的 local、direct、tun-in 替换为你文件中真实存在的 tag。不要把整个示例直接覆盖订阅生成的配置，也不要把两个 JSON 对象简单拼接在一起。
servers、rules、final、strategy 的关系
| 字段 | 实际作用 | 核对重点 |
|---|---|---|
servers | 定义 DNS 上游对象，例如 local、UDP、TLS、QUIC、HTTPS 或 FakeIP | 每个服务器的 tag 应唯一，格式要符合当前核心版本 |
rules | 按域名、域名后缀或其他条件选择 DNS 动作 | 新版本建议使用带 action 的规则，旧版字段不要直接照搬 |
final | 没有规则匹配时使用的默认 DNS server tag | 必须对应 servers 中已有的 tag；为空时官方行为是使用第一个服务器 |
strategy | 默认解析策略，可选 prefer_ipv4、prefer_ipv6、ipv4_only、ipv6_only | 强制 IPv6 可能与本地网络实际能力不匹配 |
官方 DNS 文档将 servers、rules、final 和 strategy列为顶层 DNS 配置的重要字段。查看 DNS 顶层字段 查看 DNS Rule
字段关系速记：servers 定义“有哪些 DNS”；rules 决定“哪些请求使用哪个 DNS”；final 负责“没有命中规则时怎么办”；domain_resolver 负责解析某个服务器域名；detour 决定访问上游服务器时使用哪个出站路径。
DNS 分流和 DoH：先替换 tag，再检查占位符
DNS 分流的结构可以先写成下面这样。dns.example.com、proxy-out 和 example.net 都是占位符，不能直接当作可用服务地址或真实出站名称。
{
"dns": {
"servers": [
{ "type": "local", "tag": "local" },
{
"type": "https",
"tag": "doh-placeholder",
"server": "dns.example.com",
"server_port": 443,
"path": "/dns-query",
"domain_resolver": "local",
"detour": "proxy-out"
}
],
"rules": [
{
"domain_suffix": ["example.net"],
"action": "route",
"server": "doh-placeholder"
}
],
"final": "local",
"strategy": "prefer_ipv4"
}
}
- 把
doh-placeholder替换成你自己的 DNS server tag，或保留它但确保规则引用完全一致。 - 把
proxy-out替换成已有outbounds[].tag；如果不需要指定出站，删除detour，不要填空字符串。 - 把
dns.example.com替换成实际 DoH 服务器域名，并确认domain_resolver引用的 DNS tag 存在。 - 把
example.net替换成需要分流的域名后缀；不确定时先用一条规则测试。 - 全局搜索
example.com、example.net、placeholder、proxy-out和YOUR_，确认没有遗留占位符。 - 检查
final、规则中的server、domain_resolver和detour是否分别指向正确对象。
DoH 中，domain_resolver 是解析 DoH 服务器域名的 DNS 选择；detour 是访问 DoH 服务器时使用的上游出站。两者用途不同。查看 HTTPS DNS server 查看 Dial Fields
TUN 模式下的 DNS：核心行为和客户端差异要分开看
sing-box 核心的 TUN 入站从 1.14.0 起提供 dns_mode 和 dns_address。官方定义中，disabled 不配置原生 DNS 也不劫持 DNS；native 尝试设置平台原生 DNS；hijack 在此基础上增加端口 53 劫持。启用 auto_route 时，hijack 是默认模式；未启用时默认可能是 disabled。查看 TUN 官方说明
如果手动设置 dns_address，官方要求用 hijack-dns 路由动作处理发往这些地址的 DNS 流量。Linux、Windows 和 Apple 平台对系统 DNS 的接管行为不同，图形客户端还可能增加权限、VPN 或系统扩展要求，因此“配置检查通过”不等于 TUN 已经接管系统 DNS。
| 平台 | 可先查哪里 | 权限或差异提醒 |
|---|---|---|
| Windows | 图形客户端的本地配置/Profile 编辑器、TUN 开关和运行日志 | Windows 版桌面客户端的支持范围和 TUN 行为以当前客户端页面为准；启用严格路由时，官方说明会影响非 TUN 接口上的 DNS 流量 |
| Linux | 本地配置文件、终端 sing-box check、systemd-resolved 状态和日志 | TUN、路由表、nftables 和权限可能共同影响结果；官方建议 Linux 使用 auto_redirect 改善路由 |
| macOS | 图形客户端的 Local Profile 编辑器、VPN/系统扩展授权和运行日志 | Apple 平台的系统 DNS 和网络扩展由客户端实现；菜单名称不要按其他平台照搬 |
| Android | 图形客户端的本地 Profile、VPN 权限、TUN 开关和系统 VPN 状态 | local 在 Android 图形客户端中通过平台接口解析；Android 图形客户端通常以 VPN 权限而不是桌面管理员权限为主要前置条件 |
官方图形客户端说明将 Windows、Linux、Android 和 Apple 平台分开列出；通用客户端文档也说明 Local Profile 应提供配置编辑器。具体入口名称和可用字段，以你正在使用的图形客户端当前界面为准。查看图形客户端列表 查看桌面客户端说明 查看通用 Profile 说明
FakeIP 最小结构：不是只改 dns 就结束
FakeIP 服务器的核心结构是一个 type 为 fakeip 的 DNS server，并配置 IPv4 或 IPv6 地址范围。官方示例使用 198.18.0.0/15 和 2001:2::/48 作为 FakeIP 地址范围。查看 FakeIP 官方字段
{
"dns": {
"servers": [
{ "type": "local", "tag": "local" },
{
"type": "fakeip",
"tag": "fakeip",
"inet4_range": "198.18.0.0/15",
"inet6_range": "2001:2::/48"
}
],
"rules": [
{
"domain_suffix": ["example.net"],
"action": "route",
"server": "fakeip"
}
],
"final": "local",
"reverse_mapping": true
},
"route": {
"rules": [
{ "action": "hijack-dns" }
],
"final": "direct"
}
}
这只是 FakeIP 的结构示例，不是完整代理策略。FakeIP 需要与 TUN、DNS 劫持、路由和出站逻辑一起验证；只修改 dns 而没有正确的 TUN 或路由处理，可能出现“DNS 返回了地址，但连接仍失败”。建议先用 local 配置确认普通域名可用，再加入 FakeIP 规则。
关闭后的验证：删除或停用 FakeIP server 和对应规则，恢复 final: "local"，重启客户端并清理 DNS 缓存；分别测试普通域名、原先命中 FakeIP 规则的域名和节点服务器域名。如果关闭 FakeIP 后恢复，问题范围通常集中在 FakeIP 规则、地址范围、TUN 接管或路由处理，而不是单纯 JSON 格式。
配置检查与常见报错：按现象逐层定位
| 现象 | 先查什么 | 处理与回滚 |
|---|---|---|
| JSON 或字段错误 | 逗号、引号、括号、重复顶层对象和当前核心版本 | 恢复备份，执行 sing-box check -c config.json，再逐项增加配置 |
| server tag 不存在 | final、DNS 规则、domain_resolver、detour 是否引用了现有 tag | 统一名称；不确定时先删掉新增规则和 DoH |
| DoH 解析超时 | DoH 服务器域名、domain_resolver、detour 和上游连通性 | 先改回 local；确认结构后再恢复 DoH |
| TUN 已开启但 DNS 仍走系统 | dns_mode、dns_address、auto_route、VPN 或系统扩展权限 | 先使用 hijack 和 local DNS 验证，再恢复复杂规则 |
| 部分域名打不开 | strategy、IPv4/IPv6、DNS 规则顺序和 FakeIP | 临时使用 prefer_ipv4，关闭 FakeIP，只保留一个 final |
| 旧配置出现废弃字段警告 | address 旧格式、legacy DNS server、independent_cache 或旧 DNS rule 字段 | 按当前 Migration 页面迁移，不要把旧字段和新格式混用 |
independent_cache 已在 sing-box 1.14.0 标记为废弃，官方迁移文档建议删除该字段，并说明旧字段计划在 1.16.0 移除；实际处理仍应以你安装的核心版本和当前官方页面为准。查看 Migration 查看废弃功能列表 查看变更日志
一套可回滚的最终验证流程
- 备份：复制原配置文件，保留一份可以重新启动的版本。
- 检查结构：确认只有一个顶层
dns，并检查所有引用型 tag。 - 核心检查：执行
sing-box check -c config.json；图形客户端没有命令行入口时，使用配置检查按钮或启动日志完成同等检查。 - 最小启动：仅保留 local DNS、明确的 final 和 direct 出站。
- 分层测试：先测普通域名，再测规则命中的域名，最后测试 DoH、TUN 和 FakeIP。
- 记录结果：分别记录“是否能解析”“是否能连接”“是否经过 TUN”，不要把 DNS 失败、节点出站失败和路由未接管混为一谈。
- 回滚：任何新增字段导致启动失败或解析异常时，恢复上一个能启动的配置，再只增加一个变量。
判断 DNS 是否生效，不能只看配置检查通过；还要结合客户端日志、系统 DNS 状态、TUN 状态和实际域名查询结果。命令行核心与图形客户端的入口、权限和可用字段可能不同，最终以当前客户端文档为准。
常见问题
sing-box DNS 配置应该写在哪里？
写在配置文件顶层的 dns 对象中，与 inbounds、outbounds 和 route 并列。已有配置时合并字段，不要创建两个同名的顶层对象。
只配置 servers，不写 final 可以吗？
可以。官方文档说明，final 为空时会使用第一个 DNS server；但明确写出 final 更容易排错，并能避免新增服务器后默认行为发生变化。
DoH 里的 detour 和 domain_resolver 有什么区别？
domain_resolver 用于解析 DoH 服务器本身的域名；detour 用于指定访问 DoH 服务器时采用的上游出站。两者引用的 tag 都必须真实存在。
启用 TUN 后一定要配置 hijack-dns 吗？
不一定。核心行为取决于 dns_mode、auto_route 和 dns_address；如果手动设置了 dns_address，官方文档要求使用 hijack-dns 路由动作处理发往这些地址的 DNS 流量。客户端还可能有额外权限要求。
FakeIP 为什么不是只改 dns 对象？
FakeIP 还要与 TUN、DNS 劫持、路由和连接处理配合。若 DNS 能返回 FakeIP，但路由没有正确识别或接管，可能出现解析成功而连接失败。
为什么 sing-box check 通过，启动后仍然无法解析？
check 主要用于检查配置结构和字段，不能替代真实网络测试。还要检查 DNS 上游是否可达、DoH 域名是否能解析、出站 tag 是否有效、TUN 权限是否授予，以及规则是否命中。
independent_cache 还能继续写进新配置吗？
官方当前文档已将其标记为 sing-box 1.14.0 废弃，并在迁移文档中建议删除；计划移除的版本和实际兼容性应以当前核心版本及官方迁移页面为准。
常见问题
sing-box DNS 配置应该写在哪里？
写在配置文件顶层的 dns 对象中，与 inbounds、outbounds 和 route 并列；已有配置时合并字段，不要创建两个同名对象。
DoH 里的 detour 和 domain_resolver 有什么区别？
domain_resolver 用于解析 DoH 服务器域名，detour 用于指定访问该服务器时使用的上游出站，两者引用的 tag 都必须存在。
启用 TUN 后一定要配置 hijack-dns 吗？
不一定，要结合 dns_mode、auto_route 和 dns_address 判断；手动设置 dns_address 时，官方要求使用 hijack-dns 路由动作处理对应 DNS 流量。
FakeIP 为什么不是只改 dns 对象？
FakeIP 还需要与 TUN、DNS 劫持、路由和连接处理配合；只改 dns 可能出现解析成功但连接失败。
为什么 sing-box check 通过，启动后仍无法解析？
check 不能替代真实网络测试，还需检查上游可达性、DoH 域名解析、出站 tag、TUN 权限和规则命中情况。
independent_cache 还能继续使用吗？
官方已将其标记为 sing-box 1.14.0 废弃，并建议迁移时删除；具体兼容性以实际核心版本和当前官方迁移页面为准。
相关阅读
参考资料
- sing-box 配置总览：JSON 结构与 check、format、merge 命令
- sing-box DNS 顶层配置与字段说明
- sing-box DNS Rule 规则说明
- sing-box HTTPS DNS server 与 DoH 配置
- sing-box FakeIP DNS server 配置
- sing-box Dial Fields：detour 与 domain_resolver
- sing-box TUN：dns_mode、dns_address 与 auto_route
- sing-box Route Rule Action：hijack-dns
- sing-box 图形客户端列表
- sing-box for Desktop：Windows 与 Linux 客户端说明
- sing-box 图形客户端通用 Profile 说明
- sing-box Migration：DNS 格式与废弃字段迁移