sing-box TUN 模式配置教程
简答：sing-box TUN 模式配置的基本做法是创建 tun 入站，启用 auto_route，设置 route.final，并让 dns_mode 使用 hijack；首次排查建议先用已定义的 direct 出站验证虚拟网卡、路由和 DNS，再替换为实际出站。
定义：TUN 模式是通过虚拟网卡接收系统网络流量，再由 sing-box 根据路由规则转发到指定出站的一种工作方式。
适用范围、版本与权限
本文只讲 sing-box 命令行配置中的 TUN 模式，适用于 Windows、Linux 和 macOS。不同图形客户端的菜单、权限申请和日志位置可能不同；如果你使用的是图形客户端，应以该客户端实际界面和对应版本文档为准。本文按照 2026-10-18 核对到的 sing-box 官方 TUN、Route、迁移和日志文档整理。
官方 TUN 文档将 dns_mode 和 dns_address列为 sing-box 1.14.0 的变更项，将 strict_route列为 1.13.3 的变更项。这里的“变更项”不等于字段首次出现，因此不要仅凭这个版本列表判断旧版本一定不支持某个字段。sing-box 官方 TUN 文档
如果配置中存在 stack，需要按版本处理：官方迁移指南说明，sing-box 1.15.0 起使用 sing-tun 自有 TCP/IP 栈，stack 参数自 1.15.0 起废弃，并计划在 1.17.0 移除。新配置不要主动添加 stack；旧配置升级时，应先确认本机版本，再按迁移指南修改。sing-box 官方迁移指南
TUN 通常需要创建虚拟网卡、修改系统路由或设置接口 DNS，因此启动时可能需要管理员或 root 权限。不要同时运行多个会接管同一套 TUN、系统代理或默认路由的网络程序，否则日志和路由状态会互相干扰。
可直接校验的基础配置
下面的示例只定义一个 direct-out 出站，目的是先验证 TUN、自动路由和 DNS 劫持能否启动。它不是代理节点配置，也不能证明某个外部网络服务可用。保存为 Windows 的 C:\sing-box\config.json，或 Linux、macOS 的 ~/sing-box/config.json。
{
"$schema": "https://sing-box.sagernet.org/schema.json",
"log": {
"level": "info",
"output": "sing-box.log",
"timestamp": true
},
"dns": {
"servers": [
{
"type": "local",
"tag": "local-dns"
}
],
"final": "local-dns"
},
"inbounds": [
{
"type": "tun",
"tag": "tun-in",
"interface_name": "sing-box-tun",
"address": [
"172.18.0.1/30"
],
"auto_route": true,
"strict_route": true,
"dns_mode": "hijack",
"dns_address": [
"172.18.0.2"
]
}
],
"outbounds": [
{
"type": "direct",
"tag": "direct-out"
}
],
"route": {
"auto_detect_interface": true,
"rules": [
{
"inbound": [
"tun-in"
],
"ip_cidr": [
"172.18.0.2/32"
],
"action": "hijack-dns"
}
],
"final": "direct-out"
}
}示例中的标签均已定义：tun-in是 TUN 入站标签，local-dns是本地 DNS 标签，direct-out是直连出站标签，route.final也指向已存在的 direct-out。这样可以避免把不存在的 proxy-out写进配置后导致启动失败。
dns_mode: hijack用于在 TUN 上处理 DNS，dns_address指定 DNS 地址；官方文档要求设置了 dns_address后，用 hijack-dns路由规则处理发往这些地址的 DNS 流量。TUN 字段说明 Route Rule Action：hijack-dns
不要把匹配私有地址的规则放在这条 DNS 劫持规则前面。例如，若已有 ip_is_private规则，并且它位于匹配 172.18.0.2/32的规则之前，那么 DNS 劫持地址可能先被当作普通私有地址处理，后面的 hijack-dns就不会执行。添加自定义规则时，应先检查规则列表的先后顺序和首个命中结果。Route Rule 官方文档
Windows 照做步骤
- 准备目录。创建
C:\sing-box，将 sing-box 可执行文件和config.json放在该目录。右键 PowerShell，选择“以管理员身份运行”。 - 进入配置目录。管理员 PowerShell 默认工作目录可能是
C:\Windows\System32，先执行：cd C:\sing-box - 校验配置。执行：
如果本机版本的参数提示不同，先运行.\sing-box.exe check -c .\config.json.\sing-box.exe check --help，以当前版本帮助为准。sing-box 官方配置文档提供了配置检查相关命令。sing-box 官方配置文档 - 启动 TUN。校验通过后执行：
这里使用绝对路径，可以避免因为工作目录错误而找不到配置文件。.\sing-box.exe run -c C:\sing-box\config.json - 查看日志。本示例的日志文件名是
sing-box.log，相对路径通常按进程工作目录解析，因此本步骤中应检查C:\sing-box\sing-box.log。重点查看error、failed、permission、tun、route、dns和hijack。官方日志文档说明，output用于设置日志文件路径。sing-box 官方 Log 文档 - 验证系统状态。打开 Windows“网络连接”，检查是否出现 sing-box 创建的 TUN 网卡；然后执行：
这一步只用于确认本地 DNS 与 TUN 路径是否能工作，不代表实际代理出站已经配置成功。Resolve-DnsName example.com
Linux 与 macOS 的启动和验证
- 准备配置目录。在终端执行：
将配置保存为mkdir -p ~/sing-box cd ~/sing-box~/sing-box/config.json。 - 校验并启动。执行：
是否需要./sing-box check -c ./config.json sudo ./sing-box run -c "$PWD/config.json"sudo取决于安装方式和当前系统权限；如果出现permission denied、无法创建 TUN 或无法写入路由，先检查权限。 - 验证接口和路由。Linux 可执行：
macOS 可执行：ip link show ip addr show ip route
检查是否出现 TUN 接口，以及默认路由或相关路由是否发生变化。ifconfig netstat -rn - 验证 DNS。Linux 和 macOS 可执行：
如果系统没有dig example.comdig，可使用系统已有的 DNS 查询工具。随后查看日志中的dns、hijack、route和failed关键词。
命令行 sing-box 与图形客户端的权限表现不同。本文讨论的是命令行进程：Linux 通常需要足够权限创建 TUN 和修改路由，macOS 是否需要额外授权取决于安装方式和运行场景；不要把图形客户端的网络扩展提示直接套用到命令行步骤。
规则顺序、路由环回与版本排查
| 现象 | 优先检查 | 处理方法 |
|---|---|---|
| 配置无法启动 | JSON 语法、字段名、出站标签 | 先运行 check；确认 route.final和规则引用的标签都已定义。 |
| 无法创建 TUN 或修改路由 | 管理员权限、root 权限、其他 TUN 程序 | 提高权限后重启 sing-box，并暂时退出其他会接管虚拟网卡或默认路由的程序。 |
| 能按 IP 访问，但域名无法解析 | dns_mode、dns_address和 hijack-dns规则 | 确认 172.18.0.2/32的劫持规则位于可能命中的私有地址规则之前，并确认 dns.final指向已定义的 DNS 标签。 |
| 启动后出现路由环回或连接异常 | 上游网卡绑定和系统路由 | 保留 route.auto_detect_interface: true，或者按实际网卡设置 route.default_interface。官方说明中，设置 auto_detect_interface时，default_interface不生效。Route 官方文档 |
升级后旧配置出现 stack相关提示 | sing-box 版本与迁移要求 | 1.14.x 配置先按原版本文档核对；1.15.0 起不要继续新增 stack，旧配置按官方迁移指南移除；1.17.0 及以后不要依赖该字段。 |
路由规则不是“全部执行”，而是按列表顺序进行匹配，先命中的规则先执行。因此，新增 DNS 劫持规则时，应插入现有规则列表前部，并检查它前面是否已有针对私有地址、接口或入站的匹配条件。配置更新后要重新运行 check并重启进程，不能只保存文件而不重载。
验证完成后再替换实际出站
基础配置启动成功后，再将 direct-out替换为实际出站。官方出站文档列出了不同出站类型及其字段；每种类型的服务器地址、端口、认证和 TLS 参数都不同，不能把一种出站的字段直接套到另一种类型。sing-box 官方 Outbound 文档
替换时只检查两处：第一，在 outbounds数组中完整定义新的出站并设置唯一 tag；第二，将 route.final改成这个已经定义的标签。不要只把 direct-out改名为未定义的 proxy-out。如果使用本机 SOCKS5 服务，可参考官方 SOCKS 出站字段；服务器、端口、用户名、密码和订阅令牌必须使用你自己已核实的值，分享配置前请打码。sing-box 官方 SOCKS Outbound 文档
完成替换后，按“校验配置—启动—看日志—看 TUN 接口—查路由—查 DNS—测试应用”的顺序复测。这样可以把 TUN、DNS、路由和实际出站分开定位，避免一次改动多个部分。
补充说明
本文是第三方使用指南，不是 NPC-Cloud 官方页面。sing-box 字段、版本行为和图形客户端菜单可能继续变化，实际操作应以本机版本对应的官方文档为准。本文没有提供未核实的服务状态、价格、测速或节点结论。
常见问题
sing-box TUN 模式一定要配置代理出站吗？
不一定。首次排查可以只配置已定义的 direct 出站，用于验证 TUN、自动路由和 DNS；确认基础链路正常后，再加入实际的 SOCKS、Shadowsocks、VMess、VLESS 或其他官方支持出站。
为什么 hijack-dns 规则必须放在私有地址规则前面？
因为路由规则按列表顺序匹配，先命中的规则先执行。dns_address 使用 172.18.0.2 时，如果更早的 ip_is_private 等规则先匹配到这个地址，后面的 hijack-dns 就不会执行。
sing-box 1.14.x 是否必须删除 stack？
不能一概而论。官方迁移指南说明，stack 自 1.15.0 起废弃；1.14.x 用户应按本机版本对应的官方文档保留或迁移旧配置，不要把 1.15.0 的迁移结论直接套到 1.14.x。
sing-box 1.15.0 还要不要新增 stack？
不建议新增。官方说明 1.15.0 起 sing-tun 使用自有 TCP/IP 栈，stack 参数自 1.15.0 起废弃，并将在 1.17.0 移除；新配置应省略该字段。
Windows 运行 sing-box run -c config.json 找不到文件怎么办？
管理员 PowerShell 默认目录可能是 C:\Windows\System32。先执行 cd C:\sing-box，再使用 .\sing-box.exe run -c C:\sing-box\config.json，或者始终使用配置文件绝对路径。
macOS 命令行运行 sing-box 是否一定会弹出网络扩展权限？
不一定。命令行进程与图形客户端的权限机制不同。命令行主要检查当前用户权限、TUN 创建结果、系统路由和日志；不要把图形客户端的网络扩展提示直接当作命令行必经步骤。