sing-box
sing-box 是由开发者 @nekohasekai 创建的通用代理平台,项目地址为 github.com/SagerNet/sing-box。它以"通用代理平台"为定位,设计目标是在单一框架内支持尽可能多的代理协议,同时提供高性能的核心实现。sing-box 是目前协议支持最为全面的代理核心,AnyTLS、ShadowTLS v3、NaiveProxy 等较新协议的最佳实现均在 sing-box 中。
核心特性
- 协议支持最全面:Shadowsocks、Shadowsocks 2022、VMess、VLESS(含 Reality)、Trojan、Hysteria 2、TUIC、AnyTLS、ShadowTLS v3、NaiveProxy、WireGuard、Mieru 等几乎所有现代代理协议均已覆盖
- 入站/出站架构:统一的入站(Inbound)和出站(Outbound)概念,每种协议均可同时作为服务端和客户端使用
- TUN 模式:内置高性能 TUN 实现,支持全流量透明代理
- 路由规则:灵活的路由规则系统,支持域名、IP CIDR、GEOIP、GEOSITE、进程名、端口等多维度匹配
- DNS 模块:完整的 DNS 处理能力,支持 DoH、DoT、DoQ、DoH3 等加密 DNS,以及 FakeIP 和 redir 模式
- 官方移动端应用:iOS 和 Android 均有官方应用,是少数几个提供官方移动端支持的代理核心
- 配置验证:内置配置语法检查工具,便于排查配置错误
与 Mihomo 的定位差异
sing-box 和 Mihomo 是目前最主流的两个代理核心,各有侧重:
| 对比维度 | Mihomo | sing-box |
|---|---|---|
| 协议支持广度 | 广泛 | 更广泛(尤其是新兴协议) |
| 配置格式 | YAML(Clash 兼容) | JSON(自有格式) |
| 机场订阅兼容性 | 极高(大量机场提供 Clash 格式) | 较高(越来越多机场提供 sing-box 格式) |
| AnyTLS 支持 | 支持(较新版本) | 原生设计,支持最完整 |
| NaiveProxy 支持 | 不支持 | 支持 |
| ShadowTLS v3 支持 | 支持 | 支持,实现更完善 |
| 官方移动端应用 | 无(依赖第三方 GUI) | 有(iOS 和 Android 官方应用) |
| 规则生态成熟度 | 极高(Clash 规则集丰富) | 较高(sing-box 规则集正在完善) |
| 学习曲线 | 中(YAML 配置较直观) | 较高(JSON 配置层级较多) |
安装
Linux
方法一:官方安装脚本(Debian / Ubuntu,推荐)
bash <(curl -fsSL https://sing-box.app/deb-install.sh)
安装完成后,sing-box 会以 systemd 服务的形式管理,配置文件路径为 /etc/sing-box/config.json。
方法二:手动下载二进制文件
从 GitHub Releases 下载对应系统和架构的预编译文件:
# 以 Linux amd64 为例,版本号请替换为实际最新版
wget https://github.com/SagerNet/sing-box/releases/latest/download/sing-box-1.x.x-linux-amd64.tar.gz
tar -xzf sing-box-*.tar.gz
chmod +x sing-box-*/sing-box
mv sing-box-*/sing-box /usr/local/bin/sing-box
验证安装:
sing-box version
方法三:包管理器
# Arch Linux(AUR)
yay -S sing-box
# macOS(Homebrew)
brew install sing-box
macOS
brew install sing-box
或从 GitHub Releases 下载 sing-box-1.x.x-darwin-amd64.tar.gz(Intel)或 sing-box-1.x.x-darwin-arm64.tar.gz(Apple Silicon)。
Windows
从 GitHub Releases 下载 sing-box-1.x.x-windows-amd64.zip,解压后得到 sing-box.exe。
建议将其添加到 PATH,或配合 GUI 工具使用。Windows 平台可以使用 v2rayN(支持 sing-box 核心)或直接命令行运行。
iOS
通过 App Store 安装官方应用:
iOS 官方应用需要非中国区 Apple ID 才能下载。
Android
通过 GitHub Releases 下载官方 APK:
github.com/SagerNet/sing-box/releases
下载 sing-box-1.x.x-android-universal.apk 并安装。也可以在 Google Play 搜索 sing-box 安装。
关于 GUI 客户端
sing-box 核心本身是命令行程序。如果你希望使用图形界面,可以选择以 sing-box 为核心的 GUI 客户端:
- Windows / macOS / Linux:v2rayN(支持 sing-box 内核)、Hiddify
- Android:NekoBox、Husi、Exclave
- iOS:Shadowrocket(部分协议通过 sing-box 支持)、官方 sing-box 应用
配置文件结构
sing-box 使用 JSON 格式的配置文件,默认路径为:
- Linux:
/etc/sing-box/config.json - macOS:
~/.config/sing-box/config.json - Windows:
%APPDATA%\sing-box\config.json
完整的配置文件由以下顶层字段构成:
{
"log": { ... }, // 日志配置
"dns": { ... }, // DNS 配置
"ntp": { ... }, // NTP 时间同步(可选)
"inbounds": [ ... ], // 入站配置(本地监听)
"outbounds": [ ... ], // 出站配置(代理节点和直连规则)
"route": { ... }, // 路由规则
"experimental": { ... } // 实验性功能
}
典型客户端配置示例
以下是一个完整的客户端配置示例,演示如何配置一个 VLESS + Reality 节点,并搭配分流规则和 TUN 透明代理:
{
"log": {
"level": "warn",
"timestamp": true
},
"dns": {
"servers": [
{
"tag": "dns-direct",
"address": "https://doh.pub/dns-query",
"detour": "direct"
},
{
"tag": "dns-proxy",
"address": "https://1.1.1.1/dns-query",
"detour": "proxy"
},
{
"tag": "dns-fakeip",
"address": "fakeip"
}
],
"rules": [
{
"outbound": "any",
"server": "dns-direct"
},
{
"rule_set": "geosite-cn",
"server": "dns-direct"
},
{
"query_type": ["A", "AAAA"],
"server": "dns-fakeip"
}
],
"fakeip": {
"enabled": true,
"inet4_range": "198.18.0.0/15"
},
"final": "dns-proxy",
"independent_cache": true
},
"inbounds": [
{
"type": "tun",
"tag": "tun-in",
"inet4_address": "172.19.0.1/30",
"auto_route": true,
"strict_route": true,
"sniff": true
},
{
"type": "mixed",
"tag": "mixed-in",
"listen": "127.0.0.1",
"listen_port": 2080
}
],
"outbounds": [
{
"type": "vless",
"tag": "proxy",
"server": "your.server.ip",
"server_port": 443,
"uuid": "your-uuid-here",
"flow": "xtls-rprx-vision",
"tls": {
"enabled": true,
"server_name": "www.apple.com",
"utls": {
"enabled": true,
"fingerprint": "chrome"
},
"reality": {
"enabled": true,
"public_key": "your-public-key-here",
"short_id": "a1b2c3d4"
}
}
},
{
"type": "direct",
"tag": "direct"
},
{
"type": "block",
"tag": "block"
},
{
"type": "dns",
"tag": "dns-out"
}
],
"route": {
"rules": [
{
"protocol": "dns",
"outbound": "dns-out"
},
{
"rule_set": "geoip-cn",
"outbound": "direct"
},
{
"rule_set": "geosite-cn",
"outbound": "direct"
},
{
"rule_set": "geosite-category-ads-all",
"outbound": "block"
}
],
"rule_set": [
{
"tag": "geosite-cn",
"type": "remote",
"format": "binary",
"url": "https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-cn.srs",
"download_detour": "proxy"
},
{
"tag": "geoip-cn",
"type": "remote",
"format": "binary",
"url": "https://raw.githubusercontent.com/SagerNet/sing-geoip/rule-set/geoip-cn.srs",
"download_detour": "proxy"
},
{
"tag": "geosite-category-ads-all",
"type": "remote",
"format": "binary",
"url": "https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-category-ads-all.srs",
"download_detour": "proxy"
}
],
"final": "proxy",
"auto_detect_interface": true
}
}
入站类型说明
sing-box 支持多种入站类型,以下是客户端场景中最常用的:
mixed(混合代理入站)
同时监听 HTTP 和 SOCKS5 代理请求,供系统或应用程序使用:
{
"type": "mixed",
"tag": "mixed-in",
"listen": "127.0.0.1",
"listen_port": 2080,
"set_system_proxy": false
}
set_system_proxy 设置为 true 时,sing-box 会自动配置系统代理指向该监听端口。
tun(TUN 透明代理入站)
通过虚拟网卡接管系统全部流量,实现真正的透明代理:
{
"type": "tun",
"tag": "tun-in",
"inet4_address": "172.19.0.1/30",
"inet6_address": "fdfe:dcba:9876::1/126",
"mtu": 9000,
"auto_route": true,
"strict_route": true,
"sniff": true,
"sniff_override_destination": false,
"stack": "system"
}
| 字段 | 说明 |
|---|---|
inet4_address | TUN 虚拟网卡的 IPv4 地址,使用未被占用的私有地址段 |
auto_route | 自动设置路由,将流量引导到 TUN 接口 |
strict_route | 严格路由模式,防止流量绕过 TUN |
sniff | 嗅探流量内容,用于获取实际域名(对规则匹配很重要) |
stack | 网络栈实现:system、gvisor、mixed(推荐 system) |
关于 TUN 模式的权限
TUN 模式需要较高的系统权限:
- Linux:需要 root 或
CAP_NET_ADMIN能力 - macOS:需要 sudo / 管理员权限
- Windows:需要管理员权限,且需要安装 WinTun 驱动(通常由 GUI 工具自动处理)
- iOS / Android:通过系统的 VPN 接口实现,需要用户授权 VPN 权限
socks(独立 SOCKS5 入站)
单独监听 SOCKS5 代理请求,可附加认证:
{
"type": "socks",
"tag": "socks-in",
"listen": "127.0.0.1",
"listen_port": 1080,
"users": [
{
"username": "user",
"password": "password"
}
]
}
出站类型说明
出站(Outbound)定义了流量的发送方式。除协议出站外,还有几种特殊出站:
| 出站类型 | 说明 |
|---|---|
direct | 直接连接,不经过代理 |
block | 丢弃流量,用于广告过滤 |
dns | 将流量重定向到内置 DNS 处理 |
selector | 手动选择出站(类似 Mihomo 的 select 策略组) |
urltest | 自动测速选择延迟最低的出站 |
loadbalance | 负载均衡,将连接分散到多个出站 |
selector 和 urltest(策略组)
{
"type": "selector",
"tag": "proxy",
"outbounds": [
"auto",
"vless-node",
"hy2-node",
"direct"
],
"default": "auto"
}
{
"type": "urltest",
"tag": "auto",
"outbounds": [
"vless-node",
"hy2-node"
],
"url": "https://www.gstatic.com/generate_204",
"interval": "5m",
"tolerance": 50
}
多节点配置示例
以下展示同时配置 VLESS + Reality 和 Hysteria 2 两个节点,并通过 urltest 自动选择:
{
"outbounds": [
{
"type": "selector",
"tag": "proxy",
"outbounds": ["auto", "vless-reality", "hy2-node"],
"default": "auto"
},
{
"type": "urltest",
"tag": "auto",
"outbounds": ["vless-reality", "hy2-node"],
"url": "https://www.gstatic.com/generate_204",
"interval": "3m"
},
{
"type": "vless",
"tag": "vless-reality",
"server": "your.server.ip",
"server_port": 443,
"uuid": "your-uuid-here",
"flow": "xtls-rprx-vision",
"tls": {
"enabled": true,
"server_name": "www.apple.com",
"utls": {
"enabled": true,
"fingerprint": "chrome"
},
"reality": {
"enabled": true,
"public_key": "your-public-key-here",
"short_id": "a1b2c3d4"
}
}
},
{
"type": "hysteria2",
"tag": "hy2-node",
"server": "your.domain.com",
"server_port": 443,
"password": "your-hy2-password",
"up_mbps": 100,
"down_mbps": 300,
"tls": {
"enabled": true,
"server_name": "your.domain.com"
}
},
{
"type": "direct",
"tag": "direct"
},
{
"type": "block",
"tag": "block"
},
{
"type": "dns",
"tag": "dns-out"
}
]
}
DNS 配置详解
sing-box 的 DNS 配置比 Mihomo 更为灵活,支持多服务器路由。
FakeIP 模式
FakeIP 是推荐的 DNS 工作模式,原理与 Mihomo 类似:
{
"dns": {
"servers": [
{
"tag": "dns-fakeip",
"address": "fakeip"
},
{
"tag": "dns-direct",
"address": "https://doh.pub/dns-query",
"detour": "direct"
},
{
"tag": "dns-proxy",
"address": "https://1.1.1.1/dns-query",
"detour": "proxy"
}
],
"rules": [
{
"outbound": "any",
"server": "dns-direct",
"disable_cache": true
},
{
"rule_set": "geosite-cn",
"server": "dns-direct"
},
{
"query_type": ["A", "AAAA"],
"server": "dns-fakeip"
}
],
"fakeip": {
"enabled": true,
"inet4_range": "198.18.0.0/15",
"inet6_range": "fc00::/18"
},
"final": "dns-proxy",
"independent_cache": true
}
}
outbound: any 规则表示:DNS 查询本身(即 sing-box 发出的 DNS 请求)使用 dns-direct,这是为了防止解析 DNS 服务器地址时产生循环依赖。
分 DNS 策略
国内域名走国内 DNS,国外域名走代理 DNS,避免 DNS 污染:
{
"dns": {
"rules": [
{
"outbound": "any",
"server": "dns-direct",
"disable_cache": true
},
{
"rule_set": ["geosite-cn", "geosite-private"],
"server": "dns-direct"
},
{
"rule_set": "geosite-category-ads-all",
"action": "reject"
}
],
"final": "dns-proxy"
}
}
路由规则
sing-box 的路由规则支持丰富的匹配条件:
{
"route": {
"rules": [
{
"protocol": "dns",
"outbound": "dns-out"
},
{
"ip_is_private": true,
"outbound": "direct"
},
{
"rule_set": "geosite-category-ads-all",
"outbound": "block"
},
{
"rule_set": ["geoip-cn", "geosite-cn"],
"outbound": "direct"
},
{
"network": "udp",
"port": 443,
"outbound": "block"
}
],
"final": "proxy",
"auto_detect_interface": true
}
}
规则字段说明
| 字段 | 示例 | 说明 |
|---|---|---|
domain | ["google.com"] | 精确匹配域名 |
domain_suffix | [".google.com"] | 匹配域名后缀 |
domain_keyword | ["youtube"] | 匹配域名关键词 |
domain_regex | ["^.*\\.google\\..*$"] | 正则表达式匹配域名 |
ip_cidr | ["192.168.0.0/16"] | 匹配 IP 地址段 |
rule_set | ["geoip-cn"] | 引用规则集 |
port | [80, 443] | 匹配目标端口 |
network | "tcp" 或 "udp" | 匹配传输协议 |
protocol | "dns" | 匹配应用层协议 |
process_name | ["curl"] | 匹配进程名(需 TUN 模式) |
ip_is_private | true | 匹配私有 IP 地址 |
规则集(Rule-Set)
sing-box 使用 .srs 格式的二进制规则集,比文本格式加载更快:
{
"route": {
"rule_set": [
{
"tag": "geosite-cn",
"type": "remote",
"format": "binary",
"url": "https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-cn.srs",
"download_detour": "proxy",
"update_interval": "1d"
},
{
"tag": "geoip-cn",
"type": "remote",
"format": "binary",
"url": "https://raw.githubusercontent.com/SagerNet/sing-geoip/rule-set/geoip-cn.srs",
"download_detour": "proxy",
"update_interval": "1d"
}
]
}
}
规则集来源推荐使用 MetaCubeX 或 SagerNet 维护的版本:
| 规则集 | 说明 | 仓库 |
|---|---|---|
| geosite-cn | 中国大陆域名集合 | SagerNet/sing-geosite |
| geosite-geolocation-!cn | 非中国大陆域名 | SagerNet/sing-geosite |
| geoip-cn | 中国大陆 IP 段 | SagerNet/sing-geoip |
| geosite-category-ads-all | 广告域名集合 | SagerNet/sing-geosite |
作为服务端部署
sing-box 同样是出色的服务端程序。以下展示一个简洁的 VLESS + Reality 服务端配置:
{
"log": {
"level": "warn"
},
"inbounds": [
{
"type": "vless",
"tag": "vless-in",
"listen": "::",
"listen_port": 443,
"users": [
{
"uuid": "your-uuid-here",
"flow": "xtls-rprx-vision"
}
],
"tls": {
"enabled": true,
"reality": {
"enabled": true,
"handshake": {
"server": "www.apple.com",
"server_port": 443
},
"private_key": "your-private-key-here",
"short_id": ["a1b2c3d4"]
}
},
"sniff": true
}
],
"outbounds": [
{
"type": "direct",
"tag": "direct"
}
]
}
生成 Reality 密钥对:
sing-box generate reality-keypair
生成 UUID:
sing-box generate uuid
以 systemd 运行
官方安装脚本会自动创建 systemd 服务单元。如果手动安装,可以创建以下服务单元文件:
创建 /etc/systemd/system/sing-box.service:
[Unit]
Description=sing-box service
Documentation=https://sing-box.sagernet.org
After=network.target nss-lookup.target network-online.target
[Service]
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE CAP_SYS_PTRACE CAP_DAC_READ_SEARCH
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE CAP_SYS_PTRACE CAP_DAC_READ_SEARCH
ExecStart=/usr/local/bin/sing-box -D /var/lib/sing-box -C /etc/sing-box run
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=10s
LimitNOFILE=infinity
[Install]
WantedBy=multi-user.target
启动与管理:
systemctl daemon-reload
systemctl enable sing-box
systemctl start sing-box
systemctl status sing-box
# 查看日志
journalctl -u sing-box -f
# 重载配置(不完全重启)
systemctl reload sing-box
配置验证
在启动前,可以使用内置工具验证配置文件语法:
sing-box check -c /etc/sing-box/config.json
如果有语法错误,会输出具体的错误位置和原因。这在调试复杂配置时非常有用。
使用机场订阅
越来越多的机场开始提供 sing-box 格式的订阅链接。如果你的机场提供了 sing-box 格式订阅:
# 下载订阅配置
curl -L "https://your-airport.com/api/v1/client/subscribe?token=xxx&type=singbox" \
-o /etc/sing-box/config.json
# 验证配置
sing-box check -c /etc/sing-box/config.json
# 重启服务
systemctl restart sing-box
如果机场只提供 Clash 格式订阅,可以使用订阅转换工具(如 Sub-Converter)将其转换为 sing-box 格式。但需要注意,格式转换可能无法完整迁移所有配置细节,建议优先使用机场直接提供的 sing-box 格式。
实验性功能
sing-box 的 experimental 块中包含一些可选的增强功能:
Clash API(兼容 Mihomo API)
启用 Clash 兼容 API,可以使用 yacd、Metacubexd 等 Clash 风格的 Web 控制面板:
{
"experimental": {
"clash_api": {
"external_controller": "127.0.0.1:9090",
"external_ui": "/usr/share/metacubexd",
"external_ui_download_url": "https://github.com/MetaCubeX/metacubexd/archive/refs/heads/gh-pages.zip",
"external_ui_download_detour": "proxy",
"secret": "your-api-secret",
"store_selected": true,
"store_fakeip": true
}
}
}
启用后,可通过 http://127.0.0.1:9090/ui 访问 Web 控制面板。
store_selected 和 store_fakeip 设置为 true 时,sing-box 会在重启后保留上次手动选择的节点和 FakeIP 缓存,避免每次重启都需要重新选择。
Cache File(持久化缓存)
将 FakeIP 映射、规则集缓存等持久化到文件,避免每次重启后重新构建:
{
"experimental": {
"cache_file": {
"enabled": true,
"path": "/var/lib/sing-box/cache.db",
"store_fakeip": true,
"store_rdrc": true
}
}
}
日志配置
{
"log": {
"disabled": false,
"level": "warn",
"output": "/var/log/sing-box/sing-box.log",
"timestamp": true
}
}
日志级别从详细到简略依次为:trace / debug / info / warn / error / fatal / panic。
日常运行推荐使用 warn 或 error,调试时可以临时切换到 debug 或 trace(注意 trace 级别会产生大量日志,不适合长期开启)。
客户端支持
sing-box 的覆盖范围极广,既有官方应用,也有大量基于 sing-box 的第三方客户端:
| 平台 | 客户端 | 类型 | 获取方式 |
|---|---|---|---|
| Windows / macOS / Linux | sing-box 命令行 | 官方核心 | GitHub Releases |
| Windows / macOS / Linux | v2rayN(sing-box 内核模式) | 第三方 GUI | GitHub |
| Windows / macOS / Linux | Hiddify | 第三方 GUI | GitHub |
| iOS | sing-box 官方 App | 官方应用 | App Store(非中区) |
| iOS | Shadowrocket(部分支持) | 第三方 | App Store |
| macOS | sing-box 官方 App | 官方应用 | App Store(非中区) |
| Android | sing-box 官方 APK | 官方应用 | GitHub Releases / Google Play |
| Android | NekoBox | 第三方 | GitHub |
| Android | Husi | 第三方 | GitHub |
| Android | Exclave | 第三方 | GitHub |
| Android | Hiddify | 第三方 | GitHub / Google Play |
常见问题
Q:sing-box 和 Mihomo 我应该选哪个?
取决于你的使用场景:
- 如果你主要使用机场订阅(大多数机场提供 Clash 格式),且不需要 AnyTLS 等很新的协议,Mihomo 配合 GUI 工具更为方便
- 如果你自建节点,使用了 AnyTLS、ShadowTLS v3、NaiveProxy 等协议,或者你希望使用官方移动端应用,sing-box 是更好的选择
- 两者并不互斥,可以在不同设备上分别使用
Q:启动提示 "permission denied" 无法创建 TUN 接口?
在 Linux 上,创建 TUN 接口需要 root 权限或 CAP_NET_ADMIN 能力。可以通过以下方式解决:
# 方法一:以 root 运行(不推荐用于长期部署)
sudo sing-box run -c /etc/sing-box/config.json
# 方法二:为二进制文件设置 CAP_NET_ADMIN 能力
sudo setcap 'cap_net_admin+ep' /usr/local/bin/sing-box
Q:配置了 FakeIP 后,某些应用无法正常工作?
部分应用不兼容 FakeIP 模式。可以通过 DNS 规则为这些应用排除 FakeIP 处理:
{
"dns": {
"rules": [
{
"domain": ["stun.l.google.com"],
"server": "dns-direct",
"disable_cache": false
}
]
}
}
也可以在路由规则中强制特定进程走直连,从而绕过 FakeIP。
Q:规则集文件下载失败怎么办?
规则集的 download_detour 字段指定了下载规则集本身所使用的出站。如果在初次启动时代理尚未就绪,可能导致规则集下载失败。可以将 download_detour 临时改为 "direct" 先完成下载,然后再改回 "proxy":
{
"tag": "geosite-cn",
"type": "remote",
"format": "binary",
"url": "...",
"download_detour": "direct"
}
Q:如何查看当前连接的实时状态?
启用 Clash API 后,通过 Web 控制面板可以查看实时连接列表、流量统计和日志。
如果使用命令行,可以通过 sing-box 的 API 接口查询:
curl http://127.0.0.1:9090/connections
Q:sing-box 支持 WARP(Cloudflare WireGuard)吗?
支持。可以通过 WireGuard 出站配置 Cloudflare WARP:
{
"type": "wireguard",
"tag": "warp",
"server": "engage.cloudflareclient.com",
"server_port": 2408,
"local_address": ["172.16.0.2/32"],
"private_key": "<warp-private-key>",
"peer_public_key": "bmXOC+F1FxEMF9dyiK2H5/1SUtzH0JuVo51h2wPfgyo=",
"reserved": [0, 0, 0]
}
WARP 的密钥需要通过 WARP 客户端注册账号后获取。
相关资源
- sing-box 官方文档:sing-box.sagernet.org
- sing-box GitHub:github.com/SagerNet/sing-box
- sing-geosite 规则集:github.com/SagerNet/sing-geosite
- sing-geoip 规则集:github.com/SagerNet/sing-geoip