访问验证

sing-box TUN 模式无法启动怎么办？按报错和系统逐项排查

更新于 2026-11-03 · liuheng2024.store

简答：sing-box TUN 无法启动，先不要换节点：备份配置，确认实际内核版本，再执行配置检查；通过后关闭其他 VPN、代理和 TUN 接管程序，并按系统补齐管理员权限、网络扩展或 VPN 授权。若配置检查通过但仍失败，重点看首次出现的 permission denied、address already in use、interface not found 或 unknown field。

定义：sing-box TUN 模式是通过虚拟网卡接管系统流量的透明代理方式，启动失败通常分为配置解析失败、权限不足、虚拟网卡或网络扩展创建失败、路由或 DNS 冲突四类。

先做这三步：判断是配置错，还是 TUN 无法创建

本文为第三方使用指南，核验时间为 2026年11月3日。不同图形客户端调用的 sing-box 内核、配置目录和权限方式可能不同，因此先记录客户端显示的实际内核版本，不要只看客户端名称。

  1. 备份配置：复制当前 JSON 配置和日志文件，删除或遮盖订阅链接、密码、私钥和访问令牌后再进行排查。
  2. 检查版本与配置：在终端运行 sing-box version 查看实际内核版本；在配置所在环境执行 sing-box check。官方配置文档明确提供了 check 检查命令，JSON Schema 文档也说明配置字段应与当前二进制能力匹配。配置基础与 check 命令 JSON Schema 与当前构建字段
  3. 暂时停用其他接管网络的软件：退出其他代理客户端、WireGuard、系统 VPN、虚拟网卡工具和可能开启 TUN 的程序，只保留一个程序接管系统流量。

如果 sing-box check 已经报 JSON、字段或类型错误，先修配置，不要继续改系统权限；如果检查通过但启动时才报权限、网卡或路由错误，才进入平台排查。

按报错关键词快速分流

首次报错关键词优先判断先做什么
unknown field、unknown option配置字段与实际内核版本不匹配确认实际版本，删除或替换不被当前版本识别的字段；不要直接复制旧教程配置
permission denied、Access is denied没有创建 TUN、路由或网络扩展所需权限Windows 以管理员身份运行；Linux 检查 root 或网络管理能力；Apple 平台检查网络扩展授权
address already in use本地端口或相关资源已被其他进程占用退出其他客户端，检查配置中的本地监听端口，确认没有重复启动服务
interface not found、failed to create tun虚拟网卡、TUN 设备或平台网络扩展无法创建检查驱动、系统 VPN 授权、客户端权限和平台支持范围
启动成功但网页打不开路由、DNS、回环或规则问题先关闭 TUN 恢复网络，再逐项恢复 auto_route、DNS 和规则

官方 TUN 文档列出了 auto_route、strict_route、auto_redirect、dns_mode 和 dns_address 的作用及版本变化；因此遇到字段报错时，应以当前内核文档为准，而不是把不同版本的配置混用。官方 TUN 入站配置说明

Windows：优先检查管理员权限、虚拟网卡和冲突程序

  1. 完全退出其他代理、VPN、WireGuard 和带 TUN 功能的客户端，确认任务管理器中没有残留的 sing-box 进程。
  2. 右键客户端或终端，选择以管理员身份运行，再启动 TUN。Windows 图形客户端的官方要求包含 Windows 10 及以上；TUN 属于系统网络接管功能，普通权限启动失败时应先排除权限原因。sing-box Desktop 官方平台说明
  3. 打开“设置—网络和 Internet—高级网络设置”，观察启动前后是否出现新的虚拟适配器。若没有出现，记录首次报错，检查安全软件是否拦截虚拟网卡或网络过滤驱动。
  4. 如果提示端口占用，关闭重复启动的客户端实例，并检查配置中是否同时启用了多个相同监听端口。
  5. 如果 TUN 能启动但系统断网，先关闭 strict_route 或恢复备份配置进行验证。官方文档说明 Windows 的 strict_route 会实施更严格的路由，并可能影响某些虚拟化软件；确认网络恢复后，再结合实际需求逐项启用。

回滚：停止 TUN，恢复备份配置，关闭系统代理或 VPN 开关，确认普通网络恢复后再只开启一个 TUN 客户端。

macOS：检查网络扩展授权，不要把命令行和图形客户端混为一谈

  1. 退出其他 VPN、代理客户端和网络过滤工具，避免多个 Network Extension 同时修改路由。
  2. 在 sing-box 图形客户端中重新启动服务，留意 macOS 是否弹出添加 VPN 配置或允许网络扩展的系统提示；未授权时，TUN 可能无法建立。
  3. 打开“系统设置—网络—VPN 与过滤器”以及“系统设置—隐私与安全性”，查看是否有待允许的系统扩展、网络扩展或 VPN 配置。不同 macOS 版本的菜单文字可能不同，以当前系统界面为准。
  4. 如果使用命令行版本，确认终端进程本身具备创建 TUN 和修改路由的条件；如果使用图形客户端，则优先使用其内置的网络扩展能力。官方 Apple 客户端通过 NetworkExtension 提供非特权 TUN，部分 TUN 字段在 Apple 平台并未实现，不能直接套用 Linux 配置。Apple 平台功能与 TUN 支持范围
  5. 启动后无网络时，先关闭 TUN 验证普通网络，再检查 DNS 和路由规则；不要在未确认平台支持的情况下强行添加 strict_route 等字段。

Linux：检查 root、iproute2、nftables 和路由回环

  1. 先执行 sing-box version 和 sing-box check，再查看服务日志。使用 systemd 安装的服务可运行 sudo journalctl -u sing-box --output cat -e 查看最近日志，持续观察可用 sudo journalctl -u sing-box --output cat -f。这些服务管理命令来自官方安装文档。官方安装与 systemd 日志命令
  2. 确认服务以 root 或具备创建 TUN、修改路由的权限运行。若日志出现 permission denied，先不要改 DNS，优先处理权限。
  3. 确认系统存在 ip、路由管理能力和所需 nftables 支持。Linux 的 auto_redirect 依赖 nftables，并且官方文档将其列为 Linux 下改善 TUN 路由和避免部分网络冲突的方式。
  4. 检查配置中的 route.auto_detect_interface、route.default_interface 或出站绑定接口设置，避免 sing-box 把自身连接再次送回 TUN。官方路由文档明确提示，TUN 场景需要绑定默认网卡或自动识别接口来避免回环。官方 Route 配置说明
  5. 如果 Docker、虚拟机、容器网桥或自定义策略路由同时存在，先暂时关闭相关规则，再测试最小配置。不要一开始同时启用复杂的 route_address、规则集和自定义标记。

Linux 的建议顺序：先用 auto_route: true 验证基本启动，再根据日志决定是否启用 auto_redirect: true；每次只改一个字段，并记录改动前后的首次报错。

Android 与 iOS：重点是系统 VPN 授权和客户端能力边界

Android 图形客户端通过系统 VpnService 提供非特权 TUN；首次启动通常需要用户确认 VPN 连接授权。若系统提示未出现或授权后立即停止，检查系统 VPN 设置、后台限制、省电策略和是否已有其他 VPN 占用。官方 Android 功能表还标注了部分 TUN 选项不具备权限或未实现，因此不要照搬 Linux 的 UID、接口和严格路由参数。Android 平台功能与 TUN 支持范围

iOS 和 macOS 图形客户端通过 NetworkExtension 提供 TUN。检查系统是否允许添加 VPN 配置，并确认应用没有被系统限制后台运行。Apple 功能表显示部分字段由系统管理或未实现，出现 unknown field 或启动后断流时，应先删除平台不支持的字段，再测试基础配置。

平台回滚：停止客户端，进入系统 VPN 设置删除或关闭对应 VPN 配置，重新打开客户端并仅授权一个配置。若仍失败，保留首次报错、系统版本、客户端名称和实际内核版本，交给客户端维护者核对。

启动成功但无法上网：按 DNS、路由和规则分开验证

  1. 先验证 IP 连通性：如果能访问 IP 但域名打不开，优先排查 DNS；如果 IP 也不通，优先排查路由、默认接口和出站连接。
  2. 检查 DNS 模式：当前官方 TUN 文档将 dns_mode 分为 disabled、native 和 hijack，并说明启用 auto_route 时默认行为可能涉及 DNS 接管。不要在旧教程中直接复制已变化的 DNS 字段。
  3. 检查路由回环：配置中加入或确认 route.auto_detect_interface，避免连接服务器本身的流量进入 TUN。官方客户端示例也将该设置用于 TUN 场景。
  4. 检查规则命中：暂时使用一个明确的默认出站进行测试，确认请求是否有记录；如果只有部分域名失败，再检查 DNS 规则、直连规则和私有地址规则。
  5. 复测并回滚：每次只恢复一个高级选项，依次测试网页、DNS 和需要的应用；一旦出现断网，恢复上一步配置，而不是继续叠加字段。

官方示例同时展示了 TUN、DNS 劫持、私有地址直连和自动识别默认接口的组合，但示例不代表所有客户端都能原样使用，仍需按实际内核版本和平台支持情况调整。官方客户端配置示例

最小化排查清单：确认后再恢复复杂配置

  • 已备份原始配置，并隐藏订阅链接和凭据。
  • 已记录客户端实际调用的 sing-box 版本。
  • sing-box check 不再报告 JSON 或未知字段错误。
  • 已退出其他代理、VPN、WireGuard 和 TUN 程序。
  • 已按平台补齐管理员权限、root、VPN 授权或网络扩展授权。
  • 已确认没有重复监听端口。
  • 已先用基础 TUN 配置启动，再逐项恢复 DNS、规则和严格路由。
  • 启动后已分别测试 IP、域名、普通网页和目标应用。
  • 若失败，保留首次错误行，而不是只复制最后一行日志。

如果最小配置可以启动，而原配置不能启动，问题通常在字段兼容、路由、DNS 或规则组合；如果最小配置也无法创建 TUN，则优先回到系统权限、网络扩展、虚拟网卡和冲突程序层面。

常见问题

sing-box TUN 一打开就提示 permission denied，先改哪一项？

先确认权限，不要先改 DNS。Windows 以管理员身份运行；Linux 检查服务是否以 root 或具备网络管理能力的用户运行；Android 和 Apple 平台则检查系统 VPN 或 NetworkExtension 授权。授权后仍失败，再根据首次日志判断是网卡创建还是路由修改失败。

sing-box check 通过了，为什么 TUN 还是启动不了？

配置检查只说明 JSON 和已识别字段能够解析，不代表系统一定允许创建 TUN、修改路由或启用网络扩展。此时重点排查管理员权限、root、虚拟网卡、端口占用、其他 VPN/TUN 冲突和平台功能限制。

出现 unknown field，直接删掉这个字段可以吗？

不能盲删。先确认字段属于哪个版本以及当前客户端实际调用的内核版本；如果字段只是旧版本名称，应按当前官方 TUN 文档替换为现行字段。删除后重新执行配置检查，并观察是否引入新的路由或 DNS 问题。

TUN 启动后系统完全断网，怎样快速恢复？

先停止 sing-box 或关闭 TUN，恢复系统代理和 VPN 设置，确认普通网络恢复；然后恢复备份配置，只保留基础 TUN 和必要出站，逐项加入 DNS、auto_route、strict_route、规则集等设置。若启用 strict_route 后断网，优先检查默认接口、回环和平台兼容性。

Android 或 iOS 能不能直接使用 Linux 的 TUN 配置？

不建议直接照搬。Android 使用 VpnService，Apple 平台使用 NetworkExtension，部分 Linux 字段在移动端未实现或没有系统权限。应先使用客户端支持的基础字段，再根据平台功能表调整路由、DNS 和应用范围。

相关阅读

参考资料

  1. sing-box 官方 TUN 入站配置文档
  2. sing-box 官方配置基础与 check 命令
  3. sing-box 官方 JSON Schema 文档
  4. sing-box 官方 Route 配置文档
  5. sing-box 官方客户端配置示例
  6. sing-box Desktop 官方平台说明
  7. sing-box Apple 平台官方功能说明
  8. sing-box Android 平台官方功能说明
  9. sing-box 官方安装与 systemd 服务管理说明