sing-box 使用教程（2026）：跨平台安装、配置文件结构、订阅转换、TUN 模式与常见问题

sing-box 是目前唯一一个在 Windows、macOS、Linux、Android、iOS 上都有官方客户端、并且共用同一套配置格式的代理内核。它的定位不是「更好用的 Clash」，而是一个可以被完全掌控的通用平台：协议实现跟进最快，路由规则表达能力强，规则集是预编译的二进制，启动快、占内存少。

代价是它以 JSON 配置为中心，没有 Clash 那种「粘贴订阅就有策略组」的即时体验。如果你只想快点上网，用 Clash Verge Rev 更合适；如果你想要一份配置在五个平台上行为一致、并且愿意读文档，那 sing-box 值得投入。

sing-box 和 Clash 内核有什么本质区别？

最大的思维转换在于：Clash 里你选的是「策略组里的某个节点」，sing-box 里你选的是「某个 selector 出站当前指向哪个出站」。 两者功能等价，但写法完全不同，Clash 的配置不能直接喂给 sing-box。

各平台怎么安装？

sing-box 有「命令行内核」和「图形客户端」两种用法，按平台选：

Linux / 服务器

命令行方式最直接，适合软路由、VPS 和习惯终端的人：

# Debian / Ubuntu：官方仓库或直接下载 release 的 deb 包
sudo dpkg -i sing-box_*_linux_amd64.deb

# 配置文件默认路径
sudo nano /etc/sing-box/config.json

# 校验配置语法
sing-box check -c /etc/sing-box/config.json

# 前台运行（调试用，能直接看日志）
sudo sing-box run -c /etc/sing-box/config.json

# 作为服务开机自启
sudo systemctl enable --now sing-box

Arch 系可以从 AUR 安装，其他发行版可以直接下载 Releases 里的静态二进制，放到 /usr/local/bin 并自己写一个 systemd 单元。

Windows

两个选择：

• 官方图形客户端：下载后填入本地配置文件路径或远程配置地址即可运行，TUN 需要管理员权限。
• 在 v2rayN 或 Clash Verge Rev 里把 sing-box 当内核用：适合你已经在用这些外壳、只想借 sing-box 的协议支持。v2rayN 的内核切换方法见 v2rayN 教程。

也可以纯命令行：解压 zip 后在管理员 PowerShell 里执行 .\sing-box.exe run -c config.json。

macOS

brew install sing-box
sing-box check -c ~/.config/sing-box/config.json
sudo sing-box run -c ~/.config/sing-box/config.json

TUN 模式需要 sudo，因为要创建 utun 网卡并改路由表。想要图形界面就装官方的 macOS 客户端（社区常称 SFM），它把配置管理、节点切换、日志都做成了界面。

Android / iOS

• Android：从 GitHub Releases 或 F-Droid 安装官方 APK，导入配置后一键连接。如果你更习惯 Clash 的交互，Clash Meta for Android 上手更快。
• iOS：官方有 App Store 客户端。需要注意的是，这类网络工具在各地区商店的上架情况并不统一，能否下载取决于你的 Apple ID 账号地区——和 Shadowrocket 面临的是同一类限制。

移动端客户端都支持「远程配置」：填一个 URL，客户端定期拉取并更新，这也是多设备同步配置最省事的方式。

配置文件由哪几部分组成？

一份完整的 sing-box 配置是一个 JSON 对象，顶层有六个常用键：

先看一份最小可用配置，它只做一件事：本地开一个混合代理端口，全部流量走一个节点。

{
  "log": { "level": "info", "timestamp": true },
  "inbounds": [
    {
      "type": "mixed",
      "tag": "mixed-in",
      "listen": "127.0.0.1",
      "listen_port": 7890
    }
  ],
  "outbounds": [
    {
      "type": "trojan",
      "tag": "proxy",
      "server": "hk1.example.com",
      "server_port": 443,
      "password": "你的密码",
      "tls": { "enabled": true, "server_name": "hk1.example.com" }
    },
    { "type": "direct", "tag": "direct" }
  ],
  "route": {
    "rules": [],
    "final": "proxy"
  }
}

把这份配置里的节点信息换成你机场给的，sing-box run 起来后浏览器代理填 127.0.0.1:7890 就能用了。理解了这个骨架，剩下的都是往上加东西。

outbounds 怎么写多个节点和选择器？

真实使用中你会有几十个节点，需要一个「选择器」来切换。sing-box 用 selector 和 urltest 两种特殊出站实现：

"outbounds": [
  {
    "type": "selector",
    "tag": "节点选择",
    "outbounds": ["自动选择", "香港01", "日本01", "美国01", "direct"],
    "default": "自动选择"
  },
  {
    "type": "urltest",
    "tag": "自动选择",
    "outbounds": ["香港01", "日本01", "美国01"],
    "url": "https://www.gstatic.com/generate_204",
    "interval": "5m",
    "tolerance": 50
  },
  { "type": "hysteria2", "tag": "香港01", "server": "hk.example.com", "server_port": 443, "password": "xxx" },
  { "type": "vless", "tag": "日本01", "server": "jp.example.com", "server_port": 443, "uuid": "xxx", "flow": "xtls-rprx-vision" },
  { "type": "shadowsocks", "tag": "美国01", "server": "us.example.com", "server_port": 8388, "method": "aes-256-gcm", "password": "xxx" },
  { "type": "direct", "tag": "direct" },
  { "type": "block", "tag": "block" }
]

要点：

• 每个出站的 tag 是它的名字，route 规则和 selector 都靠 tag 引用，写错就会启动失败。
• selector 相当于 Clash 的手动选择组，客户端界面里点的就是它。
• urltest 相当于 Clash 的 url-test 自动选择组，按 interval 周期测延迟。
• 各协议需要的字段不同（Hysteria2 要 password，VLESS 要 uuid 和可能的 flow），具体差异见 代理协议科普。

route 规则怎么写分流？

route.rules 是一个数组，从上往下匹配，命中即停，都没命中就走 final：

"route": {
  "rules": [
    { "action": "sniff" },
    { "protocol": "dns", "action": "hijack-dns" },
    { "ip_is_private": true, "outbound": "direct" },
    { "rule_set": "geosite-cn", "outbound": "direct" },
    { "rule_set": "geoip-cn", "outbound": "direct" },
    { "rule_set": "geosite-category-ads-all", "outbound": "block" },
    { "domain_suffix": ["openai.com", "anthropic.com"], "outbound": "美国01" }
  ],
  "rule_set": [
    {
      "type": "remote",
      "tag": "geosite-cn",
      "format": "binary",
      "url": "https://example.com/rule-set/geosite-cn.srs",
      "download_detour": "节点选择",
      "update_interval": "7d"
    }
  ],
  "final": "节点选择",
  "auto_detect_interface": true
}

几个高频用到的匹配字段：

DNS 为什么必须单独配？

代理场景下 DNS 是最容易出问题的一环：国内域名要用国内 DNS 解析（否则 CDN 会调度到国外节点），国外域名要用代理去解析（否则解析结果被污染）。典型写法：

"dns": {
  "servers": [
    { "tag": "dns-proxy", "address": "https://1.1.1.1/dns-query", "detour": "节点选择" },
    { "tag": "dns-direct", "address": "https://223.5.5.5/dns-query", "detour": "direct" }
  ],
  "rules": [
    { "rule_set": "geosite-cn", "server": "dns-direct" },
    { "clash_mode": "Global", "server": "dns-proxy" }
  ],
  "final": "dns-proxy",
  "strategy": "prefer_ipv4"
}

如果你的网络没有 IPv6，把 strategy 设成 ipv4_only 能避免大量无效的 AAAA 查询导致的首屏变慢。

机场订阅怎么转成 sing-box 配置？

这是 sing-box 用户最常卡住的地方，因为大多数机场默认只给 Clash 和通用订阅。三条路按推荐程度排列：

1. 机场直接提供 sing-box 订阅（最优）

越来越多机场在用户中心提供「sing-box」格式的订阅链接。把这个链接填进官方客户端的「远程配置 / Remote Profile」，客户端会自动下载并按设定周期更新。这也是移动端最省事的方式。导入流程与其他客户端的共性见 机场订阅导入通用教程。

2. 用订阅转换服务

订阅转换服务能把 Clash / 通用订阅转成 sing-box JSON，输出一个新的 URL，你把这个 URL 当远程配置填进客户端。使用时注意：

• 转换服务会看到你的订阅链接，等于看到你的机场账号凭证。尽量用可信实例或自建。
• 转换出的配置使用的是服务方的模板，分流规则未必符合你的习惯，通常需要再手动改 route 部分。
• 机场更换协议或新增节点后，转换链接会自动反映，但模板本身不会自动适配新协议。

3. 手动写 outbounds

节点数量少、或你只固定用三五个节点时，直接照着上面的 outbounds 示例把节点参数填进去最可控。机场给的 vless://、hysteria2:// 链接里包含了全部参数，对照协议字段手工转换即可。

TUN 模式怎么配？

TUN 让 sing-box 在网络层接管全部流量，游戏、终端、不读系统代理的软件都会被分流。在 inbounds 里加：

{
  "type": "tun",
  "tag": "tun-in",
  "address": ["172.19.0.1/30", "fdfe:dcba:9876::1/126"],
  "auto_route": true,
  "strict_route": true,
  "stack": "mixed",
  "mtu": 9000
}

字段含义：

• auto_route：自动修改系统路由表，把默认路由指向虚拟网卡。不开 TUN 等于没接管流量。
• strict_route：更严格的路由接管，能防止流量绕过，但与某些虚拟网卡（VMware、WSL、其他 VPN）冲突概率更高，出问题先把它关掉试。
• stack：网络栈实现，system 性能最好但兼容性稍差，gvisor 兼容性最好，mixed 是折中，不确定就用 mixed。
• mtu：一般不用改，链路异常时可以调小到 1400 附近试。

桌面端开 TUN 需要管理员 / root 权限；移动端由系统 VPN 框架提供，不需要额外授权。

开了 TUN 全断网怎么办？

按这个顺序排查：

1. 权限：没有管理员权限时路由根本没改成功，日志会有 operation not permitted 之类的提示。
2. 冲突：先关掉其他 VPN、虚拟机网卡，把 strict_route 设为 false 再试。
3. DNS：确认 route 规则里有 hijack-dns 类处理，并且 dns 段落配置正确。域名全部解析失败的表现就是「什么都打不开但 ping IP 通」。
4. 回环：确认 sing-box 自己访问节点服务器的流量不会再被 TUN 抓回来。开启 auto_detect_interface 通常就能自动处理。

通用的「代理开着却上不了网」排查思路，见 代理开了却上不了网。

怎么加一个图形面板？

sing-box 支持 Clash API，配上去之后可以用浏览器面板切节点、看连接、看日志：

"experimental": {
  "clash_api": {
    "external_controller": "127.0.0.1:9090",
    "external_ui": "ui",
    "default_mode": "rule"
  },
  "cache_file": { "enabled": true, "store_fakeip": true }
}

cache_file 建议开启，它会记住你上次选的节点和规则集缓存，重启后不用重新选。default_mode 配合 route 规则里的 clash_mode 字段，就能实现「规则 / 全局 / 直连」三种模式的切换，逻辑和 Clash 的三种模式 一致。

配置报错怎么定位？

第一步永远是 sing-box check -c config.json。 它会做 JSON 语法和字段合法性校验，直接告诉你哪里不对。常见错误分三类：

调试时把 log.level 改成 debug 并用前台方式运行，能看到每条连接匹配了哪条规则、走了哪个出站，这是 sing-box 最有价值的排错手段。

sing-box 适合谁？

• 多设备、多系统，想要一份配置走天下 → sing-box。
• 需要按进程名或 App 包名做精细分流 → sing-box。
• 只想快速上网，不想读文档 → Clash Verge Rev 或手机端的 Clash Meta for Android。
• iOS 上想要脚本和重写能力 → Stash、Surge、Quantumult X 对比。

全平台客户端的取舍一览见 机场客户端怎么选。