sing-box TUN 模式如何启用：新版配置、权限与断网排查

更新于 2026-10-23 · 502jsq.online

简答：启用 sing-box TUN 模式，图形客户端直接打开 TUN 并完成系统授权；命令行需加入 tun 入站、address 和 auto_route，再用 route.auto_detect_interface 防止环回。Linux 还要检查 auto_redirect、nftables 与 NFQueue。

定义：sing-box TUN 模式是通过虚拟网卡接管系统流量的方式，区别于只接收应用主动连接的 SOCKS、HTTP 入站或系统代理。

先试这一步：图形客户端开关与命令行配置二选一

照旧教程配置后启动报错或全断网，优先检查是否仍在使用已废弃字段，以及是否缺少防止节点连接环回的路由设置。图形客户端用户先打开配置或连接页面中的 TUN、透明代理或 VPN 开关；命令行用户则在 JSON 的 inbounds 数组加入 type 为 tun 的入站。

官方 TUN 文档显示，TUN 仅支持 Linux、Windows 和 macOS；Android、iOS 通常由图形客户端通过系统 VPN 能力实现透明接入。可先查看官方 Tun 配置文档和官方图形界面客户端列表。

官方客户端资料列出 Windows 10 及以上、Linux 多种架构、Android 5.0 及以上，以及 iOS 15.0、macOS 13.0 及以上等要求；实际下载入口和系统兼容性应以Desktop 客户端说明、Android 客户端说明和Apple 平台客户端说明为准。

最小可运行完整配置：DNS、TUN、direct 出站与防环回

下面示例包含日志、DNS、TUN 入站、占位的 direct 出站和 route 防环回设置。它可以作为结构参考，但只有 direct 出站时只能直连；如果你已有其他出站，请将占位出站替换为自己的合法配置，并把路由最终出站改成实际使用的标签。

{
  "log": {
    "level": "info"
  },
  "dns": {
    "servers": [
      {
        "type": "local",
        "tag": "local-dns"
      }
    ],
    "final": "local-dns"
  },
  "inbounds": [
    {
      "type": "tun",
      "tag": "tun-in",
      "interface_name": "tun0",
      "address": [
        "172.19.0.1/30",
        "fdfe:dcba:9876::1/126"
      ],
      "auto_route": true,
      "strict_route": true
    }
  ],
  "outbounds": [
    {
      "type": "direct",
      "tag": "direct"
    }
  ],
  "route": {
    "rules": [
      {
        "action": "sniff"
      },
      {
        "protocol": "dns",
        "action": "hijack-dns"
      },
      {
        "ip_is_private": true,
        "outbound": "direct"
      }
    ],
    "final": "direct",
    "default_domain_resolver": "local-dns",
    "auto_detect_interface": true
  }
}

示例中的 172.19.0.1/30、IPv6 地址和 tun0 是示例值，使用前应检查是否与本机局域网、容器网段或其他虚拟网卡冲突；冲突时替换为未占用的私有地址段。auto_detect_interface 会让出站连接默认绑定实际默认网卡，用于降低节点连接再次进入 TUN 的环回风险。相关结构可核对官方代理客户端示例、官方 Route 配置文档和官方 Direct 出站文档。

如果你的配置使用远程出站，应把示例中的 direct 替换为实际出站标签；未核实具体出站协议、服务器地址或认证字段时，不要直接复制他人的完整订阅配置。

新版字段怎么迁移：address、dns_mode 与 stack

官方文档标注，address 自 sing-box 1.10.0 起使用，并作为 TUN 接口地址字段；inet4_address 和 inet6_address 已在 sing-box 1.10.0 废弃，官方迁移说明要求将它们合并到 address。因此，新配置应优先写：

官方 TUN 文档标注，dns_mode 与 dns_address 自 sing-box 1.14.0 起提供。disabled 不设置原生 DNS且不劫持 DNS，native 尽可能设置平台原生接口 DNS，hijack 还会处理 53 端口 DNS 流量；启用 auto_route 时默认使用 hijack，未启用时默认使用 disabled。

如果设置了 dns_address，官方文档要求配置 hijack-dns 路由规则处理发往这些地址的 DNS 流量。新手可先不手动填写 dns_address，确认 TUN、出站和基础解析正常后再增加 DNS 变量。版本变更以官方 Tun 字段说明和官方迁移说明为准。

五个平台的权限与启用路径

Windows：导入配置后打开 TUN。若提示创建网卡、写入路由或权限不足，退出客户端，右键程序选择“以管理员身份运行”后重试。若同时开启系统代理，先关闭系统代理做对照，避免把系统代理和 TUN 的效果混在一起。官方 Desktop 页面明确说明其提供 TUN 透明代理功能。

macOS：使用 Apple 平台客户端导入配置，打开 TUN 或 VPN 开关，在系统提示中允许添加 VPN 配置。确认时执行 ifconfig，查看是否出现 utun 接口；如果没有接口，优先检查系统授权和客户端服务日志。Apple 平台客户端使用 NetworkExtension 提供非特权 TUN 实现，具体能力以Apple 客户端功能说明为准。

Linux：命令行启动通常需要创建 TUN 和写入路由的权限。官方文档说明，auto_redirect 仅支持 Linux，要求 auto_route 已启用，并建议 Linux 用户使用；其预匹配需要内核支持 nfnetlink_queue。如果系统没有 nftables 或 NFQueue 能力，先关闭 auto_redirect 做对照，不要同时修改 MTU、DNS 和路由。

Android：图形客户端通过系统 VPN 机制接管流量，首次打开时允许 VPN 连接。官方文档说明，Android VPN 默认优先于 TUN；如需让 TUN 经过 Android VPN，应在 route 中评估是否启用 override_android_vpn。普通 Android 用户不应把 root 专用的 auto_redirect 用法直接套到无 root 环境。

iOS：导入配置后打开 TUN 或 VPN 开关，并允许系统添加 VPN 配置。iOS 的系统授权不能由命令行 JSON 绕过；如果只有开关状态而没有流量，先检查系统 VPN 授权、出站配置和 DNS，而不是先修改 MTU。

启动与成功验证：配置、接口、路由、DNS 四步检查

1. 先检查 JSON：使用与配置文件相同版本的命令行程序，在配置目录执行 sing-box check。官方配置文档列出该检查命令；正常标准是命令返回成功，且没有 JSON 语法错误、未知字段或必填字段缺失。若你的版本要求显式配置路径，再按该版本帮助使用对应的 -c 参数，不要混用其他版本写法。
2. 再看虚拟网卡：Windows 执行 Get-NetAdapter；Linux 执行 ip link；macOS 执行 ifconfig。正常标准分别是出现启用状态的虚拟网卡、TUN 接口或 utun 接口。
3. 检查路由：Windows 执行 Get-NetRoute；Linux 执行 ip route；macOS 执行 route -n get default。重点看默认路由或分流路由是否指向预期接口，同时确认节点出站没有再次进入 TUN。
4. 检查 DNS：Windows、macOS 或 Linux 可执行 nslookup example.com，其中 example.com 仅为测试域名，替换为你要访问的真实域名。看是否返回地址、Server 是否为空、日志是否出现 DNS 请求；如果 IP 能通而域名不通，优先检查 DNS。

DNS 自查不能只看网页是否打开。建议在 TUN 关闭和开启两种状态分别执行一次 nslookup，记录 Server、Address 和响应结果，再结合 sing-box 日志判断 DNS 请求是否进入预期处理路径；若两次结果不同，不代表一定存在泄漏，还需要结合实际配置和系统网络环境分析。

故障排查表：启动失败、全断网与 DNS 异常

每次只修改一个参数，并保留修改前后的日志、网卡和路由结果。这样才能区分权限不足、字段过时、DNS 解析失败、默认路由环回和其他 VPN 冲突。

常见问题

sing-box TUN 模式必须配置哪些字段？

命令行配置至少需要 type 为 tun 的入站、address 和 auto_route；为减少节点连接环回，还应在 route 中设置 auto_detect_interface 或 default_interface。tag、interface_name、strict_route 等字段按平台和排查目标添加。

为什么旧教程里的 inet4_address、inet6_address 和 stack 不建议继续使用？

官方文档标注，inet4_address 与 inet6_address 已在 sing-box 1.10.0 废弃并合并到 address；stack 在 1.15.0 废弃，并将在 1.17.0 移除。新版配置应优先使用 address，并删除 stack。

Linux 是否一定要开启 auto_redirect？

不是所有平台都能使用。官方文档说明 auto_redirect 仅支持 Linux，要求 auto_route 已启用，并建议 Linux 用户使用；预匹配还需要内核支持 nfnetlink_queue。没有对应能力时，先关闭该字段做对照。

开启 TUN 后全断网，最快怎么恢复？

先关闭 TUN 或退出客户端恢复网络，再检查出站是否可用、address 是否与本机网段冲突、auto_route 是否生效，以及 route.auto_detect_interface 是否设置。恢复后一次只改一个字段。

dns_mode 和 dns_address 应该怎么开始配置？

新手可先使用 auto_route 启用后的默认 DNS 行为，不急着填写 dns_address。若手动填写 dns_address，必须同步检查 hijack-dns 路由规则，否则可能出现域名无法解析但 IP 可连接。

Android 和 iOS 为什么会弹出 VPN 授权？

移动系统通常通过 VPN 机制实现图形客户端的 TUN 接管，因此需要系统授权。未授权时，即使 JSON 字段正确，也可能没有预期流量；排查时还应关闭其他 VPN。

相关阅读

• 连接问题排查
• 设备配置指南
• 更多客户端使用指南

参考资料

1. Tun - sing-box 官方配置文档
2. 图形界面客户端 - sing-box 官方客户端列表
3. sing-box for Desktop 官方客户端说明
4. sing-box for Android 官方客户端说明
5. sing-box for Apple platforms 官方客户端说明
6. Apple 客户端功能 - sing-box 官方说明
7. Proxy Client - sing-box 官方示例
8. Route - sing-box 官方配置文档
9. Direct - sing-box 官方出站文档
10. Migration - sing-box 官方迁移说明
11. Introduction - sing-box 官方配置结构与检查命令