sing-box TUN 模式配置与排查:从最小配置到断网定位
简答:如果 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 | 迁移到 address | check 报未知字段时先删除旧字段 |
route_address | 用于设置导入 TUN 的自定义目标网段 | 范围过大可能改变默认路由 |
route_exclude_address | 用于排除局域网、容器或特定网段 | 局域网、Docker 或虚拟机无法访问时检查排除范围 |
stack | 1.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 等等级,参见官方日志配置说明。不同版本和图形客户端封装的具体文本可能不同,以下按关键词类别判断。
| 现象 | 日志或系统检查重点 | 处理顺序 |
|---|---|---|
| 无法创建 TUN | permission、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 问题,不能据此断定一个固定最佳值。
验证闭环:按六层顺序逐项确认
- 版本:执行
sing-box version,记录实际内核版本和客户端类型。 - 配置:执行
sing-box check -c config.json;正常是无错误返回,异常先处理 JSON、旧字段、出站标签和路由引用。 - 启动与日志:启动后确认进程持续运行,按
tun、route、dns、dial、loopback分类读取日志。 - TUN 接口:Windows 看
Get-NetIPInterface,Linux 看ip -br link,macOS 看ifconfig,Android 看 VPN 状态和客户端状态。 - 路由与 DNS:Windows 看
Get-NetRoute和Resolve-DnsName;Linux 看ip route show table all、ip rule show和resolvectl;macOS 看netstat -rn与scutil --dns。 - 应用流量:先用 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 或目标应用请求。