sing-box 客户端配置与使用指南：导入失败、启动无网怎么排查

更新于 2026-10-25 · allzezecloud.xyz

简答：拿到订阅却导入失败、启动后没网或部分 App 不通，先按“确认格式—选择客户端—导入配置—检查 JSON—排查 TUN、DNS 和路由”处理。判定标准是配置能通过 check、节点标签存在、权限已授予且 DNS 与默认出口都能正常工作。

定义：sing-box 是使用 JSON 配置的网络连接工具，核心负责解析配置和处理流量，图形客户端负责配置管理、系统代理、TUN 或平台 VPN 权限。

30 秒速查：先看你手里的内容是什么

本文是第三方使用指南，不是官方页面。sing-box 使用 JSON 配置，官方图形客户端负责管理本地或远程配置；如果你把不匹配的订阅格式直接导入，最常见结果就是空白配置、解析失败或启动后没有有效出站。

手里的内容	能否直接当作 sing-box 配置	最快处理方式
完整 sing-box JSON	可以先检查	保存为 `config.json`，运行 `sing-box check -c config.json`
Clash YAML	不能直接当作 sing-box JSON	使用兼容转换方式或重新生成 sing-box 格式，转换后仍要检查字段
Base64 编码节点文本	不是完整 JSON 配置	先确认提供方是否有 sing-box 专用远程配置
单条节点链接	通常不是完整配置	确认客户端是否支持该链接类型，或手动补成 outbound
远程配置 URL	取决于返回内容	确认 URL 返回的是 sing-box JSON，而不是 HTML、YAML 或错误页

三个最常用的命令如下。format -w 会直接写回文件，执行前建议复制一份原配置；配置中的占位符必须替换后才能检查。

sing-box check -c config.json
sing-box format -w -c config.json
sing-box run -c config.json

官方配置总览说明 sing-box 使用 JSON，并列出 check、format 等命令；字段结构可参考官方 Configuration Introduction。

先选对客户端：核心、图形客户端和第三方客户端不是一回事

核心程序负责读取 JSON、建立入站和出站、执行 DNS 与路由；图形客户端负责配置导入、启动服务以及 Windows、Linux、Android 或 Apple 平台所需的系统代理和 VPN 能力。官方客户端列表只列出项目维护的图形客户端，其他声称使用 sing-box 内核的项目需要单独核验，不能仅凭名称判断归属。

平台	官方页面列出的方向	首次使用建议	核验入口
Windows	sing-box for Desktop	先导入远程或本地配置，再决定是否启用 TUN	Desktop 页面
Linux	sing-box for Desktop 或命令行核心	先用 check 检查，再用 run 启动；桌面客户端与命令行不要同时接管同一配置	Desktop 页面
Android	sing-box for Android	安装后导入配置，启动 Android VPN 授权；应用分流问题再检查 TUN	Android 页面
iOS、macOS、Apple tvOS	sing-box for Apple platforms	按系统提示允许 VPN 或网络扩展，再导入本地或远程配置	Apple platforms 页面

官方客户端总览明确列出 Android、Apple 平台、Windows 和 Linux 的对应客户端；Desktop 页面也列出 Windows 和 Linux 的系统要求。下载入口、系统版本和文件名以官方页面及 Releases 页面实时显示为准。

按平台导入配置：路径以所用版本界面为准

Windows 和 Linux Desktop

打开 sing-box for Desktop，进入配置文件或 Profiles 管理区域。
选择新增本地配置或新增远程配置；远程配置填写完整 URL，本地配置选择 JSON 文件。
保存后在配置列表中选中该配置，再进入 Dashboard 或运行控制区域启动。
首次启用 TUN 时，按系统提示授予管理员或网络权限；如果只是验证节点，先用系统代理模式测试。

Desktop 官方页面确认其用途是管理并运行本地或远程配置，并提供 TUN 等平台能力。具体按钮名称可能随版本变化，因此以当前界面中的配置管理、Dashboard 和运行控制入口为准。

Linux 命令行

把配置保存为当前目录下的 config.json。
运行检查命令，先处理 JSON 语法、未知字段、标签不存在等错误。
需要格式化时备份文件，再运行 format；确认配置内容无误后再 run。

sing-box check -c config.json
sing-box format -w -c config.json
sing-box run -c config.json

Android

从官方 Android 页面列出的分发入口核对应用。
在应用的配置或 Profiles 页面新增本地配置，或新增 Remote Profile 并填写配置 URL。
保存后选中该配置，在 Dashboard 或运行控制区域启动。
系统弹出 VPN 授权时选择允许；如果只有部分应用不通，再检查应用排除列表、分流规则和 DNS。

iOS 和 macOS

从官方 Apple platforms 页面核对应用来源和系统要求。
进入配置或 Profiles 页面，新增本地配置或 Remote Profile，填写 URL 后保存。
在 Dashboard 或运行控制区域选中配置并启动，按系统提示允许 VPN 或网络扩展。
如果 macOS 更新后配置或设置没有继承，先备份现有数据，再查看官方迁移说明，不要直接删除旧目录。

可替换配置模板：代理、分组、TUN、DNS 和 rule-set 一起检查

下面是用于学习和改写的示例，不包含真实节点。把所有尖括号占位符替换为实际值后，才可以运行 sing-box check。示例使用 SOCKS 代理作为占位 outbound；如果你的节点是 VLESS、VMess、Trojan、WireGuard 或其他类型，只替换对应 outbound，不能只改标签名。

{
  "log": {
    "level": "info"
  },
  "dns": {
    "servers": [
      {
        "type": "local",
        "tag": "local"
      }
    ],
    "final": "local"
  },
  "http_clients": [
    {
      "tag": "rule-http",
      "detour": "direct",
      "domain_resolver": "local"
    }
  ],
  "inbounds": [
    {
      "type": "tun",
      "tag": "tun-in",
      "address": [
        "172.19.0.1/30"
      ],
      "auto_route": true,
      "strict_route": true
    },
    {
      "type": "mixed",
      "tag": "mixed-in",
      "listen": "127.0.0.1",
      "listen_port": 2080
    }
  ],
  "outbounds": [
    {
      "type": "socks",
      "tag": "proxy-a",
      "server": "<节点服务器域名或地址>",
      "server_port": <端口>,
      "version": 5,
      "username": "<用户名>",
      "password": "<密码>",
      "domain_resolver": "local"
    },
    {
      "type": "socks",
      "tag": "proxy-b",
      "server": "<第二节点服务器域名或地址>",
      "server_port": <端口>,
      "version": 5,
      "username": "<用户名>",
      "password": "<密码>",
      "domain_resolver": "local"
    },
    {
      "type": "selector",
      "tag": "proxy-select",
      "outbounds": [
        "auto",
        "proxy-a",
        "proxy-b",
        "direct"
      ],
      "default": "auto"
    },
    {
      "type": "urltest",
      "tag": "auto",
      "outbounds": [
        "proxy-a",
        "proxy-b"
      ],
      "url": "https://www.gstatic.com/generate_204",
      "interval": "3m",
      "tolerance": 50
    },
    {
      "type": "direct",
      "tag": "direct"
    }
  ],
  "route": {
    "rule_set": [
      {
        "type": "remote",
        "tag": "example-rules",
        "format": "source",
        "url": "https://<规则集地址>",
        "update_interval": "1d",
        "http_client": "rule-http"
      }
    ],
    "rules": [
      {
        "action": "sniff"
      },
      {
        "protocol": "dns",
        "action": "hijack-dns"
      },
      {
        "ip_is_private": true,
        "action": "route",
        "outbound": "direct"
      },
      {
        "rule_set": [
          "example-rules"
        ],
        "action": "route",
        "outbound": "proxy-select"
      },
      {
        "protocol": "stun",
        "action": "reject"
      }
    ],
    "default_domain_resolver": "local",
    "default_http_client": "rule-http",
    "auto_detect_interface": true,
    "final": "proxy-select"
  }
}

这个示例不能直接执行，因为 <节点服务器域名或地址>、<端口>、用户名、密码和规则集地址都是占位符。替换后，先检查 JSON，再确认节点类型和认证字段与实际订阅一致。

字段	用途	修改时注意
`mixed`	同时提供 SOCKS 和 HTTP 入站	示例监听地址只用于本机；端口以配置和系统占用情况为准
`selector`	手动在分组出口间切换	`outbounds` 中的标签必须真实存在
`urltest`	按测试 URL 和间隔选择候选出口	不能把 DIRECT 放进 urltest 候选；测试结果只代表该测试地址下的连接表现
`rule_set`	引用远程规则集进行分流	远程 URL、格式和标签必须匹配；更新间隔按使用场景调整
`http_client`	指定下载远程规则集使用的 HTTP Client	新配置优先使用该字段，不要继续新增已废弃的 `download_detour`
`default_domain_resolver`	为需要解析域名的出站提供默认解析器	节点服务器是域名时，保留它或在对应 outbound 中配置 `domain_resolver`
`route.final`	未命中规则时的兜底出口	它是 route 对象的字段，放在 JSON 中的位置不影响行为；真正要注意的是 rules 数组顺序
`action: reject`	拒绝匹配到的连接	不要再用 block 或 dns 特殊出站代替规则动作

官方文档说明了 TUN 下的 sniff、DNS 劫持、私有地址直连、默认域名解析器和自动识别网卡等配置思路，可参考Client、Rule Action、Route 和Tun 文档。

TUN、系统代理和 Mixed：按问题选择，不要同时开启多个接管工具

系统代理依赖应用主动遵循 HTTP 或 SOCKS 设置，部分非 HTTP 应用、UDP 和 ICMP 流量可能不会经过系统代理。TUN 通过虚拟网络接口接管更多流量，但通常需要系统权限，并可能与其他 VPN、WireGuard、企业安全软件或另一个 TUN 客户端争抢默认路由。Mixed 是本地代理入口，适合给支持 HTTP 或 SOCKS 的应用使用，本身不等于 TUN。

场景	优先选择	判断标准
只想验证节点和网页连接	系统代理或 Mixed	先减少接管范围，确认节点、认证和 DNS 基础功能
部分应用不遵循系统代理	TUN	确认系统 VPN 权限，并检查应用分流和排除列表
已经运行其他 VPN 或 WireGuard	先停掉其他接管工具	一次只保留一个主要 VPN/TUN 接管者，再逐个恢复
规则集经常变化	远程 rule-set + http_client	设置合理更新间隔，更新失败时保留本地初始文件或检查网络

远程配置和远程规则集的自动更新间隔不要设置得过短。更新失败时，先确认 URL 返回的是预期格式，再检查 DNS、默认出站、HTTP Client 和网络权限；不要把完整订阅 URL 提交给不可信的转换服务。

按现象排查：导入失败、启动无网、规则不生效和 DNS 异常

现象	先查什么	处理步骤
配置导入失败	返回内容和格式	确认不是 HTML、Clash YAML、Base64 或空响应；保存为本地 JSON 后运行 `sing-box check -c config.json`
check 报未知字段或标签不存在	配置版本和引用关系	检查字段所在版本文档，核对 route 引用的 outbound、DNS server、rule-set 和 HTTP Client 标签
启动后完全无网	TUN 权限、final、出站和路由循环	先关闭 TUN 改用系统代理；确认 `route.final` 指向存在的 outbound，并保留 `auto_detect_interface` 或按平台配置默认网卡
只有域名打不开	DNS 劫持和域名解析器	确认 `sniff` 和 `hijack-dns` 在前，DNS server 标签存在，节点域名有 `domain_resolver` 或默认解析器
规则集下载失败	URL、HTTP Client 和更新缓存	浏览器或命令行核对 URL 返回内容，再检查 `http_client`、`default_http_client` 和 `detour`；新配置不要新增 `download_detour`
部分 App 不走连接	系统代理覆盖范围	改用 TUN 测试，并检查 Android 或 Apple 的应用分流、排除列表和 VPN 权限
UDP、实时通信或音视频异常	节点 UDP 能力和 STUN 规则	示例中的 `protocol: stun` 加 `action: reject` 会拒绝 STUN，请按需删除或改写；不要在需要 WebRTC 或 NAT 穿透时直接照抄
DNS 泄漏疑虑	系统 DNS、TUN 和 DNS 劫持	先关闭客户端记录一次 DNS 检测结果，再启用 TUN 和 hijack-dns 重测；对比解析服务器是否变化，并检查系统 DNS 是否仍被其他 VPN 接管

DNS 泄漏检测只能说明检测时观察到的解析路径，不能替代对配置、系统 VPN 和应用行为的检查。可以继续参考站内的DNS 泄漏是什么？30 秒在线检测与按设备排查。

如果规则顺序需要调整，先保留 sniff 和 DNS 劫持，再处理私有地址、rule-set 和最终出口。官方路由规则说明规则按列表顺序匹配；route.final 只是没有其他规则匹配时使用的默认出口。

特殊出站的迁移、域名解析器设置以及 macOS 数据迁移，应以官方 Migration 文档为准；版本变化较快时，不要依据旧教程恢复已废弃字段。

完成配置后的自查清单

客户端来源能否在官方客户端列表或对应平台页面核对。
手里的订阅是完整 sing-box JSON，还是 Clash YAML、Base64、单节点链接或远程 URL。
占位符是否全部替换，配置是否通过 sing-box check。
selector、urltest、proxy 出站和 direct 标签是否全部存在。
urltest 候选中是否没有 DIRECT，且测试地址、间隔与实际用途匹配。
rules 是否先执行 sniff 和 DNS 劫持，再执行私有地址、rule-set 和其他分流。
节点服务器是域名时，是否设置了 domain_resolver 或 route.default_domain_resolver。
rule-set 是否通过 http_client 下载，是否仍误用了已废弃的 download_detour。
TUN、Mixed、系统代理是否只开启了需要的模式，其他 VPN 或 WireGuard 是否已经停止。
启用 TUN 前后是否分别做过 DNS 检测，并记录系统 DNS 和客户端 DNS 的变化。
远程订阅是否只在可信客户端中使用，泄露后是否按提供方流程撤销或重新生成。

常见问题

sing-box 可以直接导入 Clash YAML 吗？

不能把 Clash YAML 直接当作 sing-box JSON 使用。两者字段结构不同，应使用兼容转换方式或重新生成 sing-box 配置，导入后再运行 sing-box check。

sing-box 导入配置后启动但无法联网怎么办？

先关闭 TUN，改用系统代理或 Mixed 测试；然后检查 route.final、outbound 标签、DNS server 标签、节点域名解析器和系统权限。若同时运行其他 VPN 或 WireGuard，先停掉其他接管工具。

sing-box 的 TUN、系统代理和 Mixed 有什么区别？

系统代理依赖应用主动遵循代理设置；TUN 通过虚拟网络接口接管更多流量，但需要系统权限；Mixed 提供 HTTP 和 SOCKS 本地入口，适合支持代理设置的应用，不等于 TUN。

selector 和 urltest 应该怎么选？

selector 适合手动选择出口，urltest 适合在候选节点中按测试地址和间隔自动选择。urltest 只放可测试的代理出站，不要把 DIRECT 放进候选列表。

rule-set 下载失败要检查什么？

先确认 URL 返回的是规则集内容，再检查 route.rule_set 的标签、format、更新间隔、http_client 和其 detour。新配置应使用 http_client，不要继续新增已废弃的 download_detour。

为什么配置里要有 sniff 和 hijack-dns？

sniff 用于协议识别，hijack-dns 把 DNS 请求交给 sing-box 的 DNS 模块。启用 TUN 或域名分流时，缺少这些规则可能导致域名识别和 DNS 处理不符合预期，规则顺序也需要保留。

配置检查命令怎么写？

在配置文件所在目录运行 sing-box check -c config.json；需要格式化时先备份，再运行 sing-box format -w -c config.json；检查通过不代表节点、权限、DNS 或远程规则集一定可用。