咖啡加速器-跨境加速器-回国加速器

sing-box TUN 模式配置与排查:从最小配置到断网定位

更新于 2026-11-16 · cf-x.site

简答:如果 sing-box 开启 TUN 后出现全断网、启动即退出或只有部分程序无法联网,先不要同时修改 DNS、MTU 和规则。按“版本与权限→check 配置→TUN 接口→路由→DNS→应用流量”的顺序排查,先用不含旧字段、也不把 DNS detour 指向空出站的最小配置确认 TUN 基础链路。本文按 Windows、Linux、macOS、Android 分开说明,资料核对日期为 2026-11-16,具体字段仍以本机 sing-box 版本的 check 结果为准。

定义:sing-box TUN 模式是创建虚拟网卡并接管系统 IP 流量的方式,适合处理不读取系统代理的程序,但同时依赖配置、权限、路由和 DNS 条件。

先试这一步:用最小 TUN 配置确认问题在哪一层

如果你看到“开启 TUN 后全断网”“配置保存后启动即退出”或“浏览器能用、其他程序不通”,先备份原配置,记录实际内核版本,再用下面的基线配置测试。该配置只用于确认 TUN、系统路由和直连出站是否能工作,不包含远端节点,也不能证明代理出站已经可用。

config.json:

{ "$schema": "https://sing-box.sagernet.org/schema.json", "log": { "level": "info", "timestamp": true }, "dns": { "servers": [ { "type": "local", "tag": "local-dns" } ] }, "inbounds": [ { "type": "tun", "tag": "tun-in", "address": [ "172.19.0.1/30", "fdfe:dcba:9876::1/126" ], "auto_route": true, "strict_route": true, "route_address": [ "0.0.0.0/1", "128.0.0.0/1", "::/1", "8000::/1" ], "route_exclude_address": [ "192.168.0.0/16", "10.0.0.0/8", "172.16.0.0/12", "fc00::/7" ] } ], "outbounds": [ { "type": "direct", "tag": "direct" }, { "type": "block", "tag": "block" } ], "route": { "auto_detect_interface": true, "final": "direct" } }

示例使用 inbounds、outbounds、dns 和 route 等配置块;sing-box 官方配置文档同时列出了 check、format 和 merge 命令,可参考官方配置结构与检查说明。

校验与启动命令:

  • Windows:sing-box.exe check -c config.json,再用管理员 PowerShell 执行 sing-box.exe run -c config.json。
  • macOS/Linux:sing-box check -c config.json,再根据安装方式执行 sudo sing-box run -c config.json。
  • 正常判据:check 无错误返回;run 持续运行;日志没有反复出现配置解析、权限或 TUN 创建错误。
  • 异常判据:出现 unknown field、invalid value、permission denied、address already in use 或 TUN creation failed,先处理版本、权限或冲突软件。

这里的 final 是直连,只能验证 TUN 和基础网络路径;如果最小配置能启动,但加入远端出站后失败,下一步应检查远端地址、端口、认证、TLS 和节点路径,而不是继续修改 TUN 网卡。

版本与字段:哪些写法要迁移,哪些不要直接复制

先执行 sing-box version,不要只根据图形客户端名称判断内核版本。官方 TUN 文档显示,TUN 字段在 1.10.0、1.12.0、1.13.3、1.14.0 和 1.15.0 等版本存在变化;当前页面抓取日期为 2026-11-16,第三方客户端封装的实际内核仍需本机 check 核实。

字段或功能处理建议排查重点
address新配置优先使用确认 IPv4 或 IPv6 前缀格式有效
inet4_address、inet6_address迁移到 addresscheck 报未知字段时先删除旧字段
route_address用于设置导入 TUN 的自定义目标网段范围过大可能改变默认路由
route_exclude_address用于排除局域网、容器或特定网段局域网、Docker 或虚拟机无法访问时检查排除范围
stack1.15.0 起废弃,新的配置不要加入旧配置应删除后重新 check
dns_mode、dns_address官方文档标注自 1.14.0 起提供旧版本或二次封装内核必须以 check 结果为准

官方迁移指南明确说明,stack 自 sing-box 1.15.0 起废弃,并将在 1.17.0 移除;迁移方式是删除该参数。官方 TUN 文档还说明,dns_mode 和 dns_address 自 1.14.0 起提供,不能把它们直接复制到更旧的内核中。相关内容见官方迁移指南和官方 Tun 字段文档。

旧字段改写示例:

{ "type": "tun", "inet4_address": ["172.18.0.1/30"], "inet4_route_address": ["0.0.0.0/1", "128.0.0.0/1"], "stack": "system" }

可改为:

{ "type": "tun", "address": ["172.18.0.1/30"], "route_address": ["0.0.0.0/1", "128.0.0.0/1"] }

如果你的版本不是 1.15.0 或更高,是否接受某个字段不能凭文章推断,直接执行本机 sing-box check -c config.json,以输出结果为准。

四个平台怎么启用:权限、菜单和接口检查

Windows:管理员权限→TUN 设置→接口与路由

图形客户端通常从“设置→网络或 TUN”进入开关;命令行则使用管理员 PowerShell 启动。不同客户端的菜单名称可能不同,找不到 TUN 选项时先确认当前客户端不是只有 SOCKS 或 HTTP 入站。

Get-NetIPInterface | Sort-Object InterfaceIndex | Format-Table InterfaceIndex,InterfaceAlias,AddressFamily,ConnectionState,NlMtuBytes Get-NetRoute -AddressFamily IPv4 | Sort-Object RouteMetric | Format-Table DestinationPrefix,NextHop,InterfaceIndex,RouteMetric,Protocol Resolve-DnsName example.com -DnsOnly

  • 正常:出现或启用 TUN 虚拟接口;路由表出现预期路由;DNS 查询返回 A 或 AAAA 记录。
  • 异常:没有 TUN 接口,检查管理员权限、网络扩展和其他 VPN;路由没有变化,检查 auto_route;DNS 超时,检查 DNS、53 端口和防火墙。
  • 例外:如果规则让测试域名走直连,出口 IP 不变不能单独证明 TUN 未生效。

Microsoft Get-NetIPInterface 文档用于查看接口状态;Microsoft Get-NetRoute 文档用于查看目标前缀、下一跳、接口和路由指标;Microsoft Resolve-DnsName 文档用于执行 DNS 查询。

Linux:root 权限→auto_route→再考虑 auto_redirect

命令行运行通常需要 root 权限,或具备创建 TUN、修改路由和使用 nftables 的能力。建议先只启用 auto_route 验证基础路径,再单独测试 auto_redirect。

ip -br link ip -br addr ip route show table all ip rule show resolvectl status curl -v https://example.com

  • 正常:出现 sing-box 创建的 TUN 接口;路由表和 ip rule 有对应变化;curl 可以建立连接。
  • 异常:接口不存在,检查 root 权限和 TUN 设备;规则存在但连接回环,检查 route.auto_detect_interface 或 route.default_interface;启用 auto_redirect 后失败,检查 nftables、nfqueue 和容器防火墙。
  • 例外:ping 网关只能证明局域网或某段 ICMP 路径可达,不能证明 TCP、DNS、TLS 或应用流量正常。

官方文档说明,auto_redirect 仅支持 Linux,需要同时启用 auto_route,并依赖 nftables 等内核能力;官方还指出它可改善 TUN 路由并减少与 Docker 桥接网络的冲突。参见TUN 的 auto_route 与 auto_redirect 说明。

macOS:系统网络扩展→TUN→utun 接口

图形客户端一般从“设置→网络扩展或 TUN”进入,并在系统弹窗中允许网络扩展或 VPN 权限。菜单名称会随客户端版本变化;如果没有 TUN 选项,先确认客户端支持 TUN,而不是仅提供 SOCKS 或 HTTP 代理。

ifconfig netstat -rn scutil --dns curl -v https://example.com

  • 正常:出现新的 utun 接口,路由表出现预期变化,DNS 状态可以读取,curl 能连接。
  • 异常:没有 utun,检查网络扩展授权;开启后全部断网,先关闭 TUN、恢复原配置,再检查默认路由和 DNS;只有一个应用不通,检查应用是否使用独立网络栈或自定义 DNS。

Android:VPN 授权→应用范围→状态栏 VPN 标识

图形客户端一般从“设置→网络或 TUN”进入,首次启用时接受 Android VPN 授权。Android 通常只允许一个 VPN 服务同时工作,因此要先关闭其他 VPN、流量过滤或安全软件提供的 VPN 功能。应用过滤建议先取消包含和排除限制,确认全局流量正常后再逐项加入。

  • 正常:状态栏出现 VPN 标识,客户端显示 TUN 或 VPN 已连接,浏览器和目标应用都能产生流量。
  • 异常:无法创建 VPN,检查其他 VPN 占用;只有部分应用不通,检查应用包含或排除列表;连接后 DNS 失败,先关闭自定义 DNS 和复杂分流,回到最小配置。
  • 例外:Android 图形客户端不一定暴露命令行版本的全部字段,不能把桌面配置原样等同于移动端界面。

按现象定位:从日志关键词回到权限、路由和 DNS

复现问题时可把日志等级临时调为 debug,确认后再改回 info。官方日志配置支持 trace、debug、info、warn、error 等等级,参见官方日志配置说明。不同版本和图形客户端封装的具体文本可能不同,以下按关键词类别判断。

现象日志或系统检查重点处理顺序
无法创建 TUNpermission、tun、network extension、已有 VPN提升权限,关闭其他 VPN,确认客户端支持 TUN
启动即退出unknown field、invalid value、JSON 解析错误先执行 check,再删除旧字段和无效引用
开启后全断网route、dial、loopback、默认路由先关闭 TUN恢复网络,再检查自动检测物理接口和路由范围
IP 能通但域名不通dns、resolver、timeout、hijack单独执行 DNS 查询,暂时移除复杂 DNS 规则
只有部分程序不通应用过滤、IPv6、QUIC、独立 DNS 或安全软件取消应用限制,分别测试 IPv4、IPv6 和 DNS
节点连接失败dial、connect、TLS、timeout先用直连基线验证 TUN,再检查出站服务器和认证

DNS 判据:Windows 使用 Resolve-DnsName example.com -DnsOnly;Linux 使用 resolvectl query example.com 或 dig example.com;macOS 使用 scutil --dns 查看解析器。正常是返回明确记录;超时、SERVFAIL 或没有可用服务器时,优先检查 DNS 服务器、53 端口、劫持规则和防火墙。

路由回环判据:如果物理网卡本身可访问网络,但日志持续出现拨号失败或连接超时,检查 route.auto_detect_interface、route.default_interface 或出站绑定接口。官方文档明确提示,启用 auto_route 时应配置这些选项之一以避免流量环回。

局域网与虚拟网卡:开启 TUN 后无法访问路由器、NAS、Docker、WSL 或 VirtualBox 时,检查目标网段是否被 route_exclude_address 排除,并查看 Windows 的 Get-NetRoute 或 Linux 的 ip route show table all。Windows 的 strict_route 可能影响 VirtualBox;Linux 的 auto_redirect 会改变透明转发路径,因此一次只调整一个开关。

MTU:只有接口、路由和 DNS 都正常,但 HTTPS 或特定应用仍卡顿时才测试 MTU。记录原值,逐步降低并重复同一请求;恢复后只能说明路径可能存在分片或 PMTU 问题,不能据此断定一个固定最佳值。

验证闭环:按六层顺序逐项确认

  1. 版本:执行 sing-box version,记录实际内核版本和客户端类型。
  2. 配置:执行 sing-box check -c config.json;正常是无错误返回,异常先处理 JSON、旧字段、出站标签和路由引用。
  3. 启动与日志:启动后确认进程持续运行,按 tun、route、dns、dial、loopback 分类读取日志。
  4. TUN 接口:Windows 看 Get-NetIPInterface,Linux 看 ip -br link,macOS 看 ifconfig,Android 看 VPN 状态和客户端状态。
  5. 路由与 DNS:Windows 看 Get-NetRoute 和 Resolve-DnsName;Linux 看 ip route show table all、ip rule show 和 resolvectl;macOS 看 netstat -rn 与 scutil --dns。
  6. 应用流量:先用 curl 或浏览器测试,再测试命令行、办公软件或其他不读取系统代理的程序。若只有一个应用异常,检查其独立代理、IPv6、QUIC、DNS 和安全软件过滤。

最小配置能够创建 TUN、生成预期路由并完成 DNS 查询后,再逐项恢复远端出站、DNS 分流、规则集、应用过滤和 MTU 调整。每次只改一个变量并保留日志,才能判断究竟是 TUN 层、DNS 层、路由层还是出站层出现问题。

本文是第三方使用指南,不是任何客户端或服务的官方网站;客户端菜单、内核版本和字段支持情况应以实际安装版本及其官方资料为准。

常见问题

sing-box TUN 模式一定要设置 stack 吗?

不需要。官方迁移指南说明,stack 自 sing-box 1.15.0 起废弃,并将在 1.17.0 移除;新配置应删除该字段。旧版本或第三方客户端是否接受它,仍以本机 check 结果为准。

为什么 sing-box 开启 TUN 后全断网?

按权限、TUN 接口、默认路由、回环和 DNS 顺序检查。确认接口存在后,查看 sing-box 自身连接是否被默认路由再次送回 TUN,同时核对 route.auto_detect_interface、route.default_interface 或等效的出站绑定设置。

dns_mode 和 dns_address 能不能直接复制到旧版本?

不能直接假设兼容。官方 TUN 文档标注这两个字段自 1.14.0 起提供;旧版本或经过封装的内核先运行 check,以实际输出为准。

Windows 只有部分软件无法联网,浏览器却正常,怎么办?

先确认该软件是否读取系统代理。TUN 负责接管 IP 层流量,但应用可能使用独立网络栈、IPv6、QUIC、自己的 DNS 或安全软件过滤。暂时取消应用过滤规则,分别测试 IPv4、IPv6 和 DNS,再查看 dial、dns、route 相关日志。

Linux 上 auto_route 和 auto_redirect 有什么区别?

auto_route 用于设置到 TUN 的路由;auto_redirect 是 Linux 专用的透明重定向机制,需要同时启用 auto_route,并依赖 nftables 等内核能力。建议先用 auto_route 验证基础路径,再单独启用 auto_redirect。

ping 通网关是不是说明 TUN 已经正常?

不是。ping 网关只能说明局域网或某段 ICMP 路径可达,不能证明 TCP、DNS、TLS、远端出站或最终应用流量正常。还要继续检查接口、路由、DNS 和 curl 或目标应用请求。

参考资料

  1. sing-box 官方 Tun 配置字段文档
  2. sing-box 官方配置结构与检查说明
  3. sing-box 官方迁移指南
  4. sing-box 官方日志配置说明
  5. Microsoft Learn:Get-NetRoute
  6. Microsoft Learn:Resolve-DnsName
  7. Microsoft Learn:Get-NetIPInterface