sing-box TUN模式启动失败怎么办？按报错定位权限、网卡与配置
简答：sing-box TUN模式启动失败，先不要反复切换DNS、路由和MTU：关闭TUN恢复普通网络，备份配置与日志，再依次执行配置检查、查看首条错误、核对系统权限和虚拟网卡。若是“启动后断网”，处理顺序与“创建TUN失败”不同，应先回滚auto_route、strict_route或DNS相关改动。
定义：sing-box TUN模式是一种虚拟网络接口接管方式，客户端通过它接收系统流量，再按路由规则交给对应出站处理；启动失败可能发生在配置解析、TUN创建、系统路由、DNS或出站连接任一层。
先做四步速查：恢复网络，再判断故障层级
本站是第三方使用指南站，不是相关客户端或配置提供方的官网。sing-box配置使用JSON结构，官方文档提供了sing-box check配置检查命令；但配置能通过检查，只能说明结构和字段基本可解析，不能证明TUN网卡、系统路由、DNS和节点出站都正常。可先查看sing-box配置概览与TUN入站配置文档。
- 关闭TUN并恢复普通网络：退出或停止sing-box，关闭系统代理；如果仍无法上网，重启客户端或系统网络连接，不要继续修改配置。
- 备份现场：复制当前JSON配置、客户端日志和错误原文，记录操作系统、sing-box核心版本、图形客户端版本以及TUN开关前后的现象。
- 检查配置：在配置文件所在目录执行
sing-box check -c config.json；如果命令参数或客户端封装方式不同，以当前版本帮助信息为准。 - 只改一项复测：先处理日志中的第一条明确错误，再重新启动TUN；每次只改一个字段，并记录成功或失败结果。
| 现象 | 优先判断 | 成功判据 | 失败时回滚 |
|---|---|---|---|
| 点击TUN立即报错或自动关闭 | 权限、TUN接口、驱动、端口或字段兼容性 | 客户端保持运行，日志不再出现创建TUN错误 | 关闭TUN，恢复上一次配置 |
| TUN显示已启动但所有网络中断 | 默认路由、strict_route、DNS或路由循环 | 系统能解析域名，浏览器或命令行可访问测试地址 | 先关闭strict_route，再关闭auto_route复测 |
| TUN正常但只有部分地址失败 | 规则、DNS、出站或节点连接 | 直连、代理和DNS测试结果能分别解释 | 恢复原规则和DNS，不调整MTU |
按日志关键词分流处理
日志位置和菜单名称会因图形客户端、系统和版本不同而变化。优先保存启动失败前后各几十行日志，保留错误原文，不要只截取“启动失败”这一句。
| 日志关键词或现象 | 先检查什么 | 处理动作与成功判据 |
|---|---|---|
permission denied、operation not permitted | 客户端是否获得系统网络/VPN授权，进程是否有足够权限 | 关闭其他代理程序后，以系统允许的管理员或授权方式启动；成功标准是TUN接口创建完成且日志不再出现权限错误。若仍失败，恢复普通模式并记录客户端版本。 |
device unavailable、create tun failed | 虚拟网卡、驱动、残留接口和其他VPN冲突 | 退出其他VPN、虚拟网卡工具和重复运行的sing-box实例，再重启客户端；Windows可在网络适配器列表中查看是否出现异常或重复虚拟接口。不要直接删除未知网卡，先记录名称并保留回滚点。 |
address already in use | 本地监听端口是否被其他进程占用 | 检查配置中的监听端口与日志实际端口，关闭重复实例后再启动。若必须改端口，只修改一个监听字段，并同步检查客户端引用的端口。 |
unknown field、deprecated | 配置字段与核心版本是否匹配 | 按当前版本文档替换或移除字段。官方TUN文档说明，部分旧路由字段已经弃用，例如inet4_route_address应改为route_address；不要把开发分支或其他客户端的字段直接复制到当前版本。 |
no route、route loop | auto_route、默认网卡、路由表和出站绑定 | 先关闭TUN恢复网络，核对默认网卡；在Linux、Windows和macOS上可检查系统默认路由。配置中启用route.auto_detect_interface或指定默认接口时，要结合当前网络环境复测，成功标准是TUN启动后仍能访问本地网关和测试域名。 |
DNS timeout、域名打不开但IP可用 | DNS服务器、DNS规则、劫持设置和路由顺序 | 先保留原DNS配置，单独测试系统DNS与sing-box DNS；不要同时修改DNS、路由和MTU。官方路由文档说明auto_detect_interface用于避免TUN下的路由循环，需与实际网卡和出站配置一起核对。 |
connection refused、握手失败 | 出站地址、端口、证书、时间和节点状态 | 这通常不是TUN创建问题。先关闭TUN，用普通网络单独验证出站；如果普通模式也失败，应转向节点、证书或远端服务排查，不要继续改TUN路由。 |
Windows：权限、虚拟网卡和路由表逐项确认
- 确认没有重复实例：退出图形客户端和后台核心，避免两个进程同时创建TUN或监听同一端口。
- 检查权限：如果日志明确出现权限错误，尝试使用客户端提供的管理员运行或服务模式；名称可能因版本不同而变化。成功判据是TUN接口能保持运行，而不是仅仅窗口没有报错。
- 查看网络适配器：打开系统网络连接或设备管理器，确认是否有对应的虚拟接口；不要依据名称猜测接口用途，先记录接口名称、状态和出现时间。
- 查看路由：在命令提示符执行
route print，记录默认路由、接口编号和TUN启动前后的变化。若TUN启动后默认路由消失或出现重复路由，先关闭auto_route或恢复备份配置。 - 查看DNS：执行
nslookup example.com作为基础对照。若系统DNS查询失败，先恢复系统网络；若系统查询成功、TUN开启后失败，再检查sing-box DNS和路由规则。
Windows下strict_route会影响严格路由行为，官方文档还提示它可能影响部分依赖特殊网络行为的应用。遇到TUN启动后局部软件无法联网时，先记录受影响程序，再临时关闭strict_route复测，不要立即改动多个路由字段。
Linux：检查TUN设备、默认路由与nftables
- 先停止sing-box并保存日志，然后执行
ip addr查看是否存在异常TUN接口。 - 执行
ip route记录默认路由、网关和出口接口；TUN启动前后各执行一次，用于比较变化。 - 如果配置使用Linux的
auto_redirect，执行nft list ruleset查看是否有对应规则；命令失败或权限不足时，不要据此断定配置错误，应先确认nftables工具和权限。 - 检查运行用户是否具备创建TUN和修改路由所需权限。日志出现
operation not permitted时，先用当前发行版的服务权限或管理员方式验证，再决定是否调整服务配置。 - 按官方TUN文档顺序复测：先只启用TUN，再测试
auto_route，最后才测试auto_redirect和DNS劫持。Linux上官方文档将auto_redirect与auto_route配合使用，并说明其依赖nftables相关能力；具体支持情况要以当前内核和发行版为准。
回滚：停止进程，删除或恢复由本次测试新增的规则前先保存输出；如果无法确认某条规则是否由sing-box创建，优先重启网络服务或系统，不要批量清空整套防火墙规则。
macOS与Android：重点看系统授权和后台限制
macOS
- 确认系统是否弹出网络扩展或VPN授权提示；若曾拒绝授权，进入系统网络设置检查相关配置是否仍存在。
- 关闭其他VPN、代理工具和浏览器独立代理，避免系统代理与TUN同时接管流量。
- 执行
route -n get default查看默认出口，再执行scutil --dns查看当前DNS信息。TUN启动前后各记录一次。 - 若日志显示TUN创建成功但网页打不开，先关闭系统代理，再分别测试域名解析和IP连接；不要把DNS失败直接判断为节点失败。
Android
- 确认系统VPN授权已允许当前客户端；Android通常只能由一个VPN服务占用系统VPN通道，先关闭其他VPN类应用。
- 检查分应用代理、排除应用、始终开启VPN和后台电池限制；这些选项可能导致“客户端显示已连接，但目标应用不走TUN”。
- 先用浏览器测试，再测试被排除或受分应用规则影响的应用。若只有某个应用失败，优先检查应用规则，不要先改DNS或MTU。
- 若TUN一启动就断开，保存客户端导出的日志或诊断信息，记录Android版本、客户端版本和授权状态；名称可能因客户端版本不同而变化。
官方TUN文档对Android、Apple、Windows、Linux的字段支持和路由行为存在差异，不能把桌面端配置原样复制到移动端；尤其是include_package、exclude_package以及Android VPN相关选项，应以当前客户端和核心版本文档为准。
最小化复测顺序：不要一次改完所有参数
当配置文件很复杂时，建议复制一份副本进行最小化复测。以下只是排查顺序，不是可以直接替换现有订阅的完整配置：
- 保留一个确认可用的出站、一个TUN入站和最基本的路由；删除或暂时注释无法确认来源的实验字段。
- 先执行
sing-box check -c config.json，再启动但不启用系统全局代理，确认核心能运行。 - 只启用TUN接口，观察是否出现创建失败、权限错误或接口重复。
- 加入
auto_route后测试默认路由；如果出现断网，回滚这一项并检查默认网卡绑定。 - 再测试
strict_route、DNS规则和DNS劫持。每次只增加一个功能。 - 最后才验证节点出站、规则集、分流和应用范围。网页可访问、DNS可解析、代理链路正常和节点握手成功是四个不同的成功判据。
官方文档显示，TUN字段会随版本发生变化，部分字段存在弃用或平台限制；截至2026-11-08，发布页和当前文档中的版本、字段仍应以你实际使用的核心和客户端为准，不能仅凭其他教程标题判断兼容性。可从sing-box Release页面核对版本，再回到对应版本文档检查字段。
安全回滚与提交诊断信息清单
- 配置：原始JSON、修改前副本、修改后的差异内容。
- 版本：操作系统版本、图形客户端版本、sing-box核心版本、配置生成来源。
- 日志：从启动前到失败后的连续片段，保留第一条明确错误及其上下文。
- 系统状态：Windows的
route print，Linux的ip addr和ip route，macOS的route -n get default与scutil --dns。 - 回滚：关闭TUN、关闭系统代理、恢复原配置、退出其他VPN；无法确认的虚拟网卡或防火墙规则不要直接删除。
如果恢复原配置后普通网络仍异常，先处理系统网络，再继续sing-box排查。不要在未备份日志的情况下反复重装客户端，因为重装可能会改变配置路径、授权状态或诊断现场。
常见问题
sing-box check通过，为什么TUN还是启动失败？
sing-box check主要用于检查配置结构和字段，不能代替系统权限、虚拟网卡、路由、DNS和出站连接测试。通过后仍需根据运行日志确认TUN是否创建成功，并比较启动前后的网络状态。
sing-box TUN启动后没有网络，应该先改DNS吗？
不建议直接改DNS。先关闭TUN确认普通网络恢复，再检查默认路由和出站绑定；如果IP连接正常但域名解析失败，才进入DNS分支。一次只修改一个字段，并保留回滚配置。
Windows需要管理员权限才能启动TUN吗？
是否需要以及授权方式取决于客户端实现、核心版本和系统环境。若日志明确出现permission denied或operation not permitted，可先按客户端提供的管理员运行或服务模式验证；如果错误没有变化，应继续检查虚拟网卡、其他VPN和版本兼容性。
可以直接复制网上的strict_route、auto_redirect配置吗？
不建议。官方TUN文档对strict_route、auto_redirect、auto_route和路由字段标注了平台限制及版本变化。应先核对当前核心版本，再用最小配置逐项恢复；其他客户端或开发分支的字段不能证明当前安装版本一定支持。
什么时候可以判断是节点问题，而不是TUN问题？
当TUN接口能够稳定创建、系统路由和DNS基础测试正常，但出站日志出现握手失败、证书错误或连接拒绝时，才更接近节点或出站问题。关闭TUN后用普通网络单独测试出站，可以进一步分层判断。
常见问题
sing-box check通过，为什么TUN还是启动失败？
配置检查只能说明JSON结构和字段基本可解析，不能证明系统权限、虚拟网卡、路由、DNS和出站连接正常。还需要查看运行日志并比较TUN启动前后的系统网络状态。
sing-box TUN启动后没有网络，应该先改DNS吗？
不建议。先关闭TUN确认普通网络恢复，再检查默认路由和出站绑定；只有在IP连接正常、域名解析失败时，才进入DNS排查。
Windows需要管理员权限才能启动TUN吗？
取决于客户端实现、核心版本和系统环境。日志出现permission denied或operation not permitted时，可先按客户端提供的管理员运行或服务模式验证，再继续检查虚拟网卡和其他VPN冲突。
可以直接复制其他教程里的strict_route和auto_redirect配置吗？
不建议。官方文档标注了这些字段的平台限制和版本变化，应先核对当前核心版本，用最小配置逐项恢复。
什么时候可以判断是节点问题，而不是TUN问题？
当TUN能稳定创建、路由和DNS基础测试正常，但出站日志出现握手失败、证书错误或连接拒绝时，才更接近节点或出站问题。关闭TUN后单独测试出站可进一步确认。