sing-box 配置文件详解：JSON结构、路由、DNS与TUN一次看懂

更新于 2026-11-01 · lmjiasu.store

简答：sing-box 配置文件本质上是 JSON 文档，核心链路可以理解为“流量进入 inbounds—DNS解析—route判断—选择 outbounds”。先用官方 schema 或检查命令验证 JSON，再按 tag、route.final 和 DNS 规则逐项排查；不要直接照搬旧版本字段，当前适用版本请以 2026-11-01 检索到的官方文档为准。

定义：sing-box 配置文件是描述入站监听、DNS解析、路由分流、出站连接及实验功能的 JSON 配置文档。

先看懂一份配置：流量到底怎样走

本站是独立的使用指南站，不是任何客户端或服务品牌的官网。理解 sing-box 配置文件时，先不要从字段名称背诵开始，而要沿着一条连接的实际路径看：应用流量先进入 inbounds，需要域名解析时由 dns 处理，随后由 route 按规则判断，最后交给 outbounds 直连、阻断、选择节点或执行自动测速。

模块	作用	常见关注点	排错方向
`log`	控制日志输出	日志级别、输出位置	先提高日志级别观察错误
`dns`	定义 DNS 服务器和 DNS 规则	`servers`、`rules`、`final`	检查服务器 tag 是否存在、规则顺序是否正确
`inbounds`	接收本机或网络流量	`mixed`、`socks`、`tun`	检查监听地址、端口和系统权限
`outbounds`	决定流量从哪里出去	节点协议、`direct`、`block`、`selector`	检查出站类型、tag及必填字段
`route`	匹配流量并选择出站	`rules`、`rule_set`、`final`	检查规则顺序和引用的出站 tag

官方配置入口给出了完整的顶层结构，包括 $schema、log、dns、ntp、certificate、endpoints、inbounds、outbounds、route、services 和 experimental。并不是每份配置都需要填写全部模块。可以先从 inbounds、outbounds、route 三部分建立最小闭环，再按需求增加 DNS、TUN 或规则集。参考：sing-box 官方配置结构。

JSON基础：先避免格式错误，再谈字段含义

sing-box 使用 JSON 作为配置格式。JSON 对引号、逗号、括号和数据类型要求严格，配置文件中不能直接写普通注释。常见错误包括把键名写成单引号、最后一个字段后多写逗号、把布尔值写成字符串，以及数组或对象括号没有闭合。

键名和字符串使用英文双引号，例如 "type": "mixed"。
true、false 和数字不要加引号。
同一对象中的字段使用逗号分隔，但最后一个字段后不要追加逗号。
配置中的 tag 应保持唯一，并在引用时逐字一致。
若编辑器支持 JSON Schema，可使用官方 schema 辅助补全和校验，但 schema 只能帮助发现结构问题，不能替你判断节点参数是否有效。

下面的代码只用于理解结构，属于“结构示例/不可直接复制”。其中没有真实节点参数，也没有覆盖所有平台权限要求。

{
  "$schema": "https://sing-box.sagernet.org/schema.json",
  "log": {
    "level": "info"
  },
  "inbounds": [
    {
      "type": "mixed",
      "tag": "mixed-in",
      "listen": "127.0.0.1",
      "listen_port": 2080
    }
  ],
  "outbounds": [
    {
      "type": "direct",
      "tag": "direct-out"
    },
    {
      "type": "block",
      "tag": "block-out"
    }
  ],
  "route": {
    "final": "direct-out"
  }
}

这份示例只创建本机 mixed 代理入口，并把未被其他规则匹配的流量交给直连出站。它不包含代理节点，因此不能被理解为“导入订阅后的完整配置”。

inbounds、outbounds和tag：配置能否连起来的关键

inbounds 是流量入口。mixed 同时提供 SOCKS 和 HTTP 服务，适合本机应用通过代理端口接入；socks 和 http 分别提供单一协议入口；tun 则创建虚拟网络接口，适合需要接管系统流量的场景。官方文档说明，mixed 入站可以通过 set_system_proxy 自动设置系统代理，但不同系统和图形客户端的权限行为并不完全相同，不能把它与 TUN 模式混为一谈。参考：mixed 入站官方说明。

outbounds 是流量出口。常见类型包括：

direct：直接连接目标地址，适合本地网络或不需要代理的流量。
block：拒绝连接，常用于广告、追踪或指定域名的阻断规则。
selector：在多个出站之间手动选择。
urltest：按设定的测试地址和周期，在多个出站中进行自动测试选择。
节点协议出站：例如 WireGuard、VMess、VLESS、Trojan、Shadowsocks 等，具体字段必须按对应官方协议页面和实际内核版本填写。

tag 是连接各模块的标识。假设某个出站的 tag 是 proxy-a，路由规则中的 outbound、selector 的 outbounds 或其他引用位置都必须写成完全相同的 proxy-a。最常见的“找不到出站”问题，不一定是节点协议错误，也可能只是 tag 拼写、大小写或数组层级不一致。

urltest 需要引用已有的出站 tag，并可设置测试 URL、周期和容忍延迟。官方文档显示，未填写测试 URL 时会使用默认地址，未填写测试周期时也有默认值；但测试结果只代表测试请求的表现，不等于所有网站、所有时段都具有相同速度。参考：URLTest 官方说明。

route和DNS：为什么规则顺序会影响结果

route.rules 是按顺序处理的路由规则集合。规则可以根据域名、域名后缀、IP 地址、端口、入站 tag、进程、网络类型或规则集匹配流量，再通过规则动作选择出站、拦截、嗅探或处理 DNS。route.final 是没有被前面规则处理时使用的默认出站；如果为空，官方文档说明会使用第一个可用于对应协议的出站，因此为了减少歧义，建议显式填写一个已经存在的出站 tag。参考：route 官方说明。

可以把规则排查简化成四步：

先确认目标流量确实进入了预期的 inbound。
再检查前面是否有更宽泛的规则提前匹配，例如一个覆盖范围很大的域名后缀或 IP 段。
确认规则引用的 outbound tag 在 outbounds 中真实存在。
最后检查 final 是否指向可用出站，避免所有未匹配流量落到错误出口。

dns 模块负责定义 DNS 服务器、DNS 规则和默认 DNS 出口。官方结构中常见字段包括 servers、rules、final 和 strategy。DNS 服务器本身也有 tag，DNS 规则引用的是 DNS server tag，而不是普通 route outbound tag，二者不要混写。DNS 规则同样要注意顺序，命中后是否继续处理取决于对应规则动作和配置逻辑。参考：DNS 官方说明。

现象	优先检查	可能的配置位置
域名无法解析	DNS server tag、服务器类型和网络可达性	`dns.servers`、`dns.final`
规则没有按域名分流	域名规则顺序、嗅探动作和目标域名是否被识别	`route.rules`
IP流量没有匹配域名规则	是否需要解析动作或 IP 规则集	`route.rules`、`rule_set`
所有流量都走同一个出口	前面的规则是否未命中、`final` 是否覆盖全部流量	`route.final`

TUN模式怎么理解：先确认平台、权限和回滚方式

TUN 入站不是“再开一个代理端口”，而是创建虚拟网络接口，并通过路由把系统或指定范围的流量交给 sing-box。官方 TUN 文档显示，address 用于设置接口地址，auto_route 用于设置默认路由，strict_route 会影响严格路由和 DNS 行为，auto_detect_interface 可用于避免 TUN 下的路由环路。TUN 对系统权限、平台能力、已有 VPN、虚拟机、容器和本地网段都可能敏感。

一份 TUN 配置至少要单独核对这些项目：

平台：官方 TUN 页面列出 Linux、Windows 和 macOS 的支持范围；移动端图形客户端还可能通过自身 VPN 框架实现不同的接管方式。
地址：address 必须是合法的 IPv4 或 IPv6 前缀，非特权模式下不能假设地址和 MTU 一定会自动配置。
自动路由：开启 auto_route 后，要同时检查默认网卡绑定或自动检测接口设置。
DNS：新版本 TUN 文档包含 dns_mode 和 dns_address，具体行为会受到平台和版本影响，不要把旧版的 DNS 字段直接复制到新配置。
回滚：修改前备份原配置；若出现断网，先停止 sing-box，恢复原配置，关闭系统代理或 VPN，再检查系统路由和 DNS 是否恢复。

官方文档显示，TUN 字段在多个版本中持续调整，例如 DNS 模式、严格路由、自动重定向和旧版 stack 字段都有版本变化。因此本文不提供一份声称适用于所有平台的“万能 TUN 配置”。需要配置 TUN 时，应先确定操作系统、图形客户端或命令行构建版本，再对照对应版本文档。参考：TUN 官方说明。

配置检查、格式化与报错排查流程

官方配置入口提供了检查和格式化命令。命令参数可能随构建版本变化，执行前应先使用当前构建的帮助信息确认用法。最短排查流程如下：

复制一份原始配置，保留可回滚版本。
用编辑器的 JSON 校验功能检查括号、双引号、逗号和数据类型。
运行当前构建支持的 sing-box check，确认配置结构和字段能被当前内核识别。
必要时使用官方文档列出的 sing-box format 整理格式，不要在格式化后覆盖唯一备份。
启动后观察日志，重点看端口占用、权限不足、字段未知、tag 不存在、DNS 失败和路由循环。
只改一个模块后重新检查，不要同时改 DNS、TUN、节点和全部路由，否则难以判断是哪一项引起问题。

官方配置页面同时列出 merge 命令，用于合并配置文件或配置目录。它适合有明确文件组织需求的用户；如果只是排查一份现成 config.json，优先使用单文件检查，避免把多个文件的来源和覆盖关系混在一起。参考：官方配置检查、格式化与合并说明。

如果配置能通过 JSON 校验但仍无法启动，通常要把问题分成两层：第一层是“当前版本是否认识这个字段”，第二层是“字段之间的引用和运行环境是否满足”。前者应查看官方变更记录和对应模块文档，后者则检查端口、权限、系统代理、网络接口、DNS 和路由。本文不把第三方转换结果或旧教程中的字段当作当前版本结论。

常见问题

sing-box 配置文件通常叫什么？

常见文件名是 config.json，但文件名本身不是关键，关键是内容必须符合当前 sing-box 版本支持的 JSON 配置结构。不同客户端可能使用自己的文件路径或配置管理方式。

为什么配置检查通过，启动后仍然无法连接？

JSON 检查只说明语法或部分结构没有明显错误，不代表端口可用、节点参数正确、DNS可达、权限充分或路由逻辑正确。应继续看启动日志，并按 inbound、DNS、route、outbound 的顺序分层排查。

route.final 应该填写什么？

应填写已经存在且适合作为默认出口的 outbound tag，例如直连出站或代理选择器的 tag。不要填写出站类型名称，也不要填写不存在的 tag。

mixed 和 tun 有什么区别？

mixed 是本机 SOCKS/HTTP 代理服务器，应用需要连接它的监听端口；tun 是虚拟网络接口，可以接管更大范围的系统流量，但通常涉及路由、权限、DNS和系统网络环境。

可以直接把旧教程里的 sing-box 配置复制过来吗？

不建议。官方文档显示多个配置字段会随版本新增、迁移或弃用，例如 TUN、DNS 和路由相关字段都有版本变化。应先确认内核版本，再对照对应官方模块文档逐项迁移。