← 返回 GitHub Proxy 最新地址发布 - GitHub 文件 , Releases 首页

sing-box 1.14 DNS TLS 配置：DoT 写法、迁移与报错排查

更新于 2026-10-28 · ghproxy.cyou

简答：sing-box 1.14 配置 DNS over TLS（DoT）时，应使用 dns.servers 中 type=tls 的新结构，不要继续使用旧版 tls://地址式 legacy 写法。最快做法是先确认三件事：type=tls、tls.server_name 与证书名称匹配、域名型 DoT 服务器配置 domain_resolver；然后执行 sing-box check，再按日志排查 853 端口和出站链路。

定义：sing-box 1.14 的 DNS TLS 配置，是通过 DNS over TLS 建立加密解析连接的 JSON 配置方式，核心字段包括 type、server、server_port、tls，以及用于解析 DoT 服务器域名的 domain_resolver。

先试这一步：三种链路与最小 DoT 配置

如果你正在把旧配置升级到 sing-box 1.14，先不要同时修改 TUN、路由和代理出站。备份原文件后，只替换 dns 部分，再执行检查。官方文档显示，DoT 新结构使用 type: tls、server、server_port 和 tls，并支持 DNS 服务器对应的 Dial Fields。可参考 sing-box DNS over TLS 官方字段说明。

先判断你要配置哪条链路
场景关键配置先验证什么
直连 DoTtype: tls，不写或不设置代理出站字段DoT 域名可解析，TCP 853 可连接，证书校验通过
经指定出站连接 DoT在 DoT DNS server 中填写 detour，值为已定义的出站 tag指定出站本身能启动，并且该出站可建立连接
DoT 服务器使用域名配置 domain_resolver，值为已定义的 DNS server tag先确认服务器域名能被该解析器解析

下面的 dot.example.invalid 和 local-dns 都是占位值，不能直接连接。使用前必须逐项替换：一是换成你已确认支持 DoT 的服务器域名；二是把 server_name 换成该服务证书对应的主机名；三是保留或替换为你配置中真实存在的 DNS server tag。

直连 DoT 模板：

{
"dns": {
"servers": [
{
"type": "tls",
"tag": "dot-dns",
"server": "dot.example.invalid",
"server_port": 853,
"tls": {
"enabled": true,
"server_name": "dot.example.invalid",
"insecure": false
},
"domain_resolver": "local-dns"
},
{
"type": "local",
"tag": "local-dns"
}
],
"final": "dot-dns",
"strategy": "prefer_ipv4"
}
}

这里的 final 指定未被规则单独匹配时使用的 DNS server；如果为空，官方文档说明会使用列表中的第一个服务器。strategy 是默认域名解析策略，可选值包括 prefer_ipv4、prefer_ipv6、ipv4_only 和 ipv6_only。详见 sing-box DNS 配置官方文档。

server_name、domain_resolver、detour 和 insecure 分别做什么

server_name：用于 TLS 握手中的主机名，并用于校验服务器返回证书的主机名。它通常应填写证书对应的域名，而不是随意填写 IP 或另一个域名。官方 TLS 文档说明，除非设置了 insecure，否则 server_name 会参与证书主机名验证，也会在支持虚拟主机时发送到握手中。可参考 sing-box TLS 通用配置。

domain_resolver：主要用于解析 DoT 服务器自身的域名。例如 server 填写 dot.example.invalid 时，sing-box 需要先通过指定的 DNS server 解析这个地址。它不等于最终业务请求一定使用的 DNS，也不能替代 final 或 DNS rules。

detour：用于让这个 DNS server 的连接通过指定出站。值必须是已经定义的出站 tag。它只改变 DoT 服务器连接采用的拨号路径，不会自动创建出站，也不会修复出站自身的认证、路由或连通性问题。DoT 官方结构把 Dial Fields 放在 DNS server 对象中，具体字段应以你实际运行版本的文档为准。

insecure：表示接受任意服务器证书。它不应作为长期修复方案；如果只是为了区分“网络连接失败”和“证书校验失败”，可以短时间测试，测试后应恢复为 false。证书错误仍应优先检查 server_name、服务端证书名称和系统时间。

经指定出站连接 DoT：可照抄的差异示例

如果直连 DoT 失败，而你确认需要让 DNS 连接经过某个已存在的出站，可以在 DoT server 对象中增加 detour。下面只展示 DNS 部分；proxy-out 必须在完整配置的 outbounds 中真实存在，否则配置不能按预期工作。

{
"dns": {
"servers": [
{
"type": "tls",
"tag": "dot-via-proxy",
"server": "dot.example.invalid",
"server_port": 853,
"tls": {
"enabled": true,
"server_name": "dot.example.invalid",
"insecure": false
},
"domain_resolver": "local-dns",
"detour": "proxy-out"
},
{
"type": "local",
"tag": "local-dns"
}
],
"final": "dot-via-proxy"
},
"outbounds": [
{
"type": "direct",
"tag": "direct"
}
]
}

这是字段位置示例，不是完整可运行配置，因为示例中的 proxy-out 没有在数组中定义。实际操作时，把它替换为你已有的出站 tag；如果暂时没有可用出站，先删除 detour，以直连方式验证 DNS 服务器、证书和 853 端口。一次只改一个变量，才能判断故障是在 DoT、出站还是路由层。

直连与 detour 的排查顺序
步骤直连 DoT经出站 DoT
1检查 DoT 域名和 domain_resolver先做同样检查
2确认本地网络能访问 853确认指定出站能启动
3检查 server_name 和证书检查出站建立连接后的 TLS 日志
4确认 final 或 rules 命中 DoT tag确认 DNS 连接确实使用了 detour

从旧版 tls:// 配置迁移到 sing-box 1.14

这一步是 1.14 用户最容易遇到的兼容问题。sing-box 官方 Legacy 页面明确写明：Legacy DNS server 格式在 1.12.0 被弃用，并在 1.14.0 移除；旧配置中的 address、address_resolver、address_strategy 等字段不能继续当作 1.14 的新写法使用。可查看 Legacy DNS 官方说明 和 官方弃用列表。

旧版写法或思路1.14 迁移方向检查重点
address: tls://域名type: tls、server: 域名不要把完整 tls:// 地址继续填入 server
address_resolverdomain_resolver填写已定义的 DNS server tag
旧版 TLS 选项tls 对象核对 server_name 和 insecure
旧版代理路径当前 DNS server 支持的 Dial Fields核对 detour 和出站 tag 是否存在
  1. 先备份：复制原 JSON 文件，保留回滚版本。
  2. 重写 server 对象：为 DoT server 增加 type: tls、server、server_port 和 tls。
  3. 处理域名解析：如果 server 是域名，增加指向已定义 DNS tag 的 domain_resolver。
  4. 删除旧字段：不要把旧版 address、address_resolver 与新结构混在同一个对象中。
  5. 检查并启动：先运行配置检查，成功后再启动服务和观察日志。

配置检查、验证标准与失败分流

sing-box 使用 JSON 配置。官方配置页提供了 sing-box check 检查命令，也提供了 sing-box format 格式化命令；命令必须在实际安装了 sing-box 二进制的环境中执行，配置路径按你的文件名替换。可参考 sing-box 配置官方介绍。

  1. 格式检查：执行 sing-box check -c config.json。如果提示 unknown field、invalid configuration 或 JSON 解析错误，先修复字段和括号，不要先开启 insecure。
  2. 启动日志：配置检查通过后启动 sing-box，记录首次出现的错误关键词。重点观察 DNS server tag、域名解析、连接超时、TLS handshake 和 certificate 等字段。
  3. 验证域名解析链路：如果日志显示 DoT 服务器域名无法解析，检查 domain_resolver 的 tag 是否拼写一致、对应 server 是否真的存在。
  4. 验证端口链路：如果出现超时或连接拒绝，先区分直连和 detour。直连失败时检查本地网络、出口和服务端端口；加入 detour 后失败，则优先检查出站和路由。
  5. 验证证书：如果出现 certificate verification failed，核对 server_name 与证书主机名，不要把临时测试结果当成长期配置。
  6. 验证实际命中：如果配置能启动但查询仍失败，检查 final、DNS rules 和客户端日志。能启动只代表配置结构通过，不代表每个查询都已经使用 DoT。

不同图形客户端可能只显示简化日志，无法直接展示每个 DNS 请求命中了哪个 server tag。这种情况下，应先在客户端中导出或查看 sing-box 核心日志；如果没有对应日志入口，就只能把“配置检查通过、核心启动、目标域名可解析、TLS 握手无错误”作为分阶段验证标准，不要把网页能打开直接等同于 DoT 已命中。

常见报错对照表

报错或现象优先检查修复后如何继续
unknown field、invalid configuration是否把 Legacy 字段放进 1.14 配置，或字段拼写错误改成 type: tls 新结构，再执行 sing-box check
DoT 服务器域名无法解析domain_resolver 是否填写真实存在的 tag先换成已确认可用的解析器，确认域名解析后再继续 TLS 排查
certificate verification failedserver_name 是否与证书主机名匹配，系统时间是否正确核对服务端资料；测试结束后保持 insecure: false
853 端口超时或连接被拒绝本地网络、出口、防火墙、服务器端口先去掉 detour 测直连，再单独测试指定出站
加入 detour 后启动失败出站 tag 是否定义，字段是否写在 DoT server 对象内恢复备份，先让直连模板通过，再重新加入出站字段
配置能启动但查询失败final、DNS rules、TUN 或路由是否改变了请求路径查看核心日志，确认查询链路和实际命中的 DNS server

FAQ：sing-box 1.14 DNS TLS 配置常见问题

sing-box 1.14 的 DoT 必须写 server_port 吗？

官方 DoT 结构将 server_port 的默认值列为 853，因此可以省略；为了便于阅读和排错，建议明确写出 853。如果服务端使用其他端口，应以服务端公开说明为准，不要凭经验修改。

为什么 server_name 不能随便填？

因为它同时参与 TLS 握手和证书主机名验证。填写与证书不匹配的域名，可能导致证书校验失败；填写 IP 也不一定符合服务端证书和虚拟主机配置。应使用服务端证书对应的主机名。

domain_resolver 是不是最终使用的 DNS？

不是。它主要用于解析 DoT server 自身的域名；最终普通域名查询使用哪个 DNS server，还要看 final 和 DNS rules。两者可以是同一个 tag，也可以按配置目标分别设置。

证书验证失败时能不能直接设置 insecure=true？

不建议长期这样做。insecure 会接受任意服务器证书，只适合短时间区分证书问题和网络问题。排查后应恢复为 false，并继续核对 server_name、证书主机名和系统时间。

旧版 tls://地址在 sing-box 1.14 还能继续使用吗？

不要把旧版 Legacy DNS server 格式直接作为 1.14 新配置。官方文档说明 Legacy 格式已在 1.14.0 移除，应迁移为 type: tls、server、server_port、tls 和必要的 Dial Fields。

配置检查通过，是否说明 DNS 一定可用？

不是。配置检查主要验证结构和字段，不能替代域名解析、853 端口、TLS 握手、出站和 TUN 路径验证。请继续查看启动日志，并按“域名解析—端口连接—证书校验—final/rules 命中”的顺序排查。

适用范围与安全提醒

本文只覆盖 sing-box 1.14 JSON 配置中的 DNS over TLS，包括新格式、Legacy 迁移、域名解析、TLS 校验、直连与指定出站排查。没有给出任何具体 DNS 服务的可用性、速度或稳定性结论；示例域名均为占位值，使用前必须自行核验。

配置文件可能包含订阅地址、访问令牌或其他敏感信息。分享日志和配置前应删除完整订阅链接、Token、私钥及服务器凭据。切换核心、DNS、TUN 或出站前先备份，出现启动失败时优先恢复备份，再逐项修改。

本文为第三方使用指南，不是 sing-box 官方页面；版本字段、客户端菜单和可用功能应以你实际安装版本及官方文档为准。

常见问题

sing-box 1.14 的 DoT 必须写 server_port 吗？

官方 DoT 结构将 server_port 默认值列为 853，可以省略；为便于排错，建议明确写出 853。其他端口必须以服务端说明为准。

domain_resolver 和 final 有什么区别？

domain_resolver 主要用于解析 DoT 服务器自身的域名；final 用于指定未被规则单独匹配时使用的 DNS server。它们可能相同，也可以按链路需求分别设置。

detour 应该写在哪里？

应写在 DoT DNS server 对象中，值为已经定义的出站 tag。它不会自动创建出站，加入前应确认对应 outbound 已存在并能正常启动。

证书验证失败能否设置 insecure=true？

不建议长期开启。它会接受任意服务器证书，只适合短时间区分证书问题与网络问题；排查后应恢复 false，并核对 server_name、证书主机名和系统时间。

旧版 tls://地址为什么在 1.14 报错？

官方文档说明 Legacy DNS server 格式在 sing-box 1.14.0 移除。应迁移到 type=tls、server、server_port、tls 和必要的 domain_resolver 或 Dial Fields 结构。

配置检查通过但 DNS 仍然失败怎么办？

按域名解析、853 端口、TLS 证书、final 或 rules、detour 出站和 TUN 路径依次检查。配置检查通过不等于网络链路已经可用。

相关阅读

参考资料

  1. sing-box 官方文档：DNS over TLS（DoT）
  2. sing-box 官方文档：TLS 通用配置
  3. sing-box 官方文档：DNS 配置总览
  4. sing-box 官方文档：Legacy DNS server 格式
  5. sing-box 官方文档：弃用功能列表
  6. sing-box 官方文档：配置检查与格式化