Sing-box 完整教程 2026：从安装到规则分流的一站式指南
很多人是从 Clash 系客户端转过来的，第一次打开 sing-box 的配置文件就被劝退了：一整份 JSON，没有图形界面替你把选项摆好，改错一个字段进程直接起不来。但这正是它的定位——它不是「又一个带界面的客户端」，而是一个把入站、出站、路由和 DNS 全部收进同一份配置的通用代理平台。理解了这一点，后面的学习路径就清楚了：先认清它和你熟悉的工具差在哪，再跑通一个服务端最小配置，然后是客户端接入、分流规则的组织方式，最后学会用校验命令和日志自己排错。本文就按这个顺序走。
一、先定位：它和 Clash 系、v2ray 系差在哪
三类工具解决的是同一件事，但组织方式完全不同：
- Clash 系（mihomo 内核 + 各类图形客户端）：重心在「规则引擎 + 订阅生态」。配置围绕节点列表和规则展开，DNS 相对附属，图形界面成熟，新手最容易上手。
- v2ray 系（v2ray-core / Xray）：重心在「协议实现」。协议支持扎实，但路由和 DNS 的表达相对朴素，复杂分流写起来啰嗦。
- sing-box：重心在「统一模型」。入站、出站、路由、DNS、规则集全部是一份 JSON 里的顶层模块，彼此引用；新协议跟进很快，TUN、DNS 劫持这些能力都是原生的一部分，而不是外挂。
「配置即代码」是它与生俱来的属性，好处和代价都很明确：好处是配置可以进版本管理、可以整段复用、行为完全可预测，换台机器把文件拷过去就能跑；代价是没有向导帮你兜底，字段名写错、引用的标签对不上，程序拒绝启动。所以用 sing-box 的第一课不是背协议，而是养成「改完先校验」的习惯，这在第二节就会用到。
一份配置的骨架由五个顶层块构成，先混个脸熟：
| 顶层块 | 管什么 | 一句话理解 |
|---|---|---|
log | 日志级别与输出 | 排错时你看的仪表盘 |
inbounds | 流量怎么进来 | 本机的入口，如 TUN、mixed 端口；服务端则是监听的协议端口 |
outbounds | 流量从哪出去 | 节点本身，或直连，或一组节点组成的策略组 |
route | 流量分给谁 | 按规则把连接指派给某个出站，最后一条 final 兜底 |
dns | 域名怎么解析 | 独立的服务器列表加规则，和路由平级 |
还有一个认知需要提前纠正：sing-box 核心本身不处理「订阅链接」。它只读本地的 JSON 配置文件。你在图形客户端里看到的「粘贴订阅地址、自动更新节点」，是客户端（或 sub-store、subconverter 这类转换工具）先把订阅拉下来生成配置，再交给核心运行。分清核心与客户端的边界，很多「为什么 sing-box 没有某某功能」的困惑会自动消失。协议本身怎么选，可以先看 科学上网协议对比 2026。
二、服务端：先跑通一个最小可用配置
自建场景里最常见的需求，是在一台 VPS 上开一个属于自己的入口。这里以 VLESS + Reality 为例，给一份能直接跑起来的最小配置——它刻意只保留必需品：一个入站、一个直连出站、基础日志。
{
"log": { "level": "info", "timestamp": true },
"inbounds": [
{
"type": "vless",
"tag": "vless-in",
"listen": "::",
"listen_port": 443,
"users": [
{ "uuid": "用 generate 命令生成的 UUID", "flow": "xtls-rprx-vision" }
],
"tls": {
"enabled": true,
"server_name": "借用的真实站点域名",
"reality": {
"enabled": true,
"handshake": { "server": "借用的真实站点域名", "server_port": 443 },
"private_key": "用 generate 命令生成的私钥",
"short_id": ["随机短 ID"]
}
}
}
],
"outbounds": [
{ "type": "direct", "tag": "direct" }
]
}需要的密钥材料不用手编，核心自带生成命令：
sing-box generate uuid # 生成用户 UUID
sing-box generate reality-keypair # 生成 Reality 公私钥对
sing-box generate rand --base64 8 # 生成随机串，可用作 short_id写完配置不要急着启动，先校验再运行，这是 sing-box 工作流里最值钱的一步：
sing-box check -c config.json # 只校验，不启动；有错会指出位置
sing-box format -w -c config.json # 顺手把格式整理齐
sing-box run -c config.json # 校验通过再正式运行长期运行一般交给 systemd 托管，官方文档给了现成的服务单元写法，这里不展开。只强调两个服务端特有的点：其一，时钟要准。Reality 和一切 TLS 握手都对系统时间敏感，服务器时区乱了、时间漂移了，表现是客户端怎么都连不上，先开 NTP 同步再谈别的。其二，服务端不需要分流规则。route 整块都可以不写，入站进来的流量默认从直连出站出去；网上很多服务端教程塞了一大段路由和 DNS，那是把客户端配置抄过来了，只会徒增出错点。
习惯了面板路线的人可以对比着看：3X-UI 自建代理完整教程 是在网页里点选生成配置，sing-box 是自己写文件。前者上手快，后者行为完全在自己手里，没有谁对谁错，运维风格不同而已。
部署检查清单
把配置放上服务器之前，逐项过一遍，能挡掉绝大多数「死活连不上」：
三、客户端接入：入站两件套、出站分组、DNS 新写法
客户端的任务比服务端多三件：接管本机流量、管好一组节点、处理好 DNS。逐个来。
3.1 入站：TUN + mixed 各管一摊
"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"
},
{
"type": "mixed",
"tag": "mixed-in",
"listen": "127.0.0.1",
"listen_port": 2080
}
]TUN 创建虚拟网卡接管全系统流量，游戏、命令行、各种不认系统代理的软件都靠它；mixed 同时提供 HTTP 和 SOCKS 代理端口，给浏览器或单个软件手动指定时用。两个都开着不冲突，前者是主力，后者是补充。
这里有个字段新旧问题必须点名：老教程里 TUN 入站写的是 inet4_address / inet6_address，这两个字段已经被 address 数组取代。照旧教程抄到新版本上，轻则警告重则不生效，见到老写法记得换成上面这种。
3.2 出站：节点是原料，策略组才是成品
节点本身只是一个个 outbound，日常使用靠策略组组织：selector 是手动切换的分组，urltest 是按延迟自动选最快的分组。把自建节点和机场节点放进同一个 proxy 组，就是最基础的「聚合」——不需要什么额外工具，配置层面天然支持。客户端一侧的节点写法与服务端入站是镜像关系（server、server_port、uuid、TLS 与 Reality 的公钥部分），此处不重复贴。
3.3 DNS： sing-box 近几个版本改动最大的地方
DNS 配置的写法在新版本里经历了一次大改，也是抄老教程最容易翻车的区域。两个关键变化：
- 服务器定义从
address字段改成type+server。以前写"address": "https://1.1.1.1/dns-query"，现在要写成"type": "https", "server": "1.1.1.1"；要让解析请求本身走代理，用detour指出站。旧格式在新版本中已被移除，照抄会直接报错。 - fake-ip 从一个开关变成一种独立的 DNS 服务器类型。以前是在
dns里开fakeip.enabled，现在是定义一个"type": "fakeip"的服务器，再用规则或final把需要它的域名指过去。另外，拦截某类域名也不再依赖特殊的rcode://地址写法，而是给 DNS 规则加action: "predefined"并指定返回码。
按新写法的一份客户端 DNS 骨架如下：
"dns": {
"servers": [
{ "type": "udp", "tag": "local", "server": "223.5.5.5" },
{ "type": "https", "tag": "remote", "server": "1.1.1.1", "detour": "proxy" },
{ "type": "fakeip", "tag": "fakeip", "inet4_range": "198.18.0.0/15" }
],
"rules": [
{ "rule_set": "geosite-cn", "server": "local" },
{ "rule_set": "geosite-category-ads-all", "action": "predefined", "rcode": "REFUSED" }
],
"final": "fakeip",
"reverse_mapping": true
}思路是三层：国内域名交给本地 DNS 就近解析；明确要拦的（广告类）直接返回拒绝；其余全部走 fake-ip，由内核记住域名与假 IP 的对应关系，连接真正发出时再按路由规则处理，这样解析环节既不泄露查询记录、也不受污染结果影响。不习惯 fake-ip 的人可以把 final 改成 remote（经代理的 DoH 真实解析），兼容性略好、防污染能力略弱，二选一看自己的网络环境。无论选哪种，有一条不变：给远程解析服务器加 detour 指向代理出站，漏了它，DNS 查询会从本地网络裸奔出去，分流做得再细也是白做。
3.4 图形客户端与订阅
不想碰命令行的，用官方图形端：Android 是 SFA、iOS 是 SFI、macOS 是 SFM，都是 SagerNet 官方出品，在其中导入配置或订阅即可；iOS 端受商店区域限制，需要非大陆区 Apple ID，具体办法见 iOS 代理完整指南 2026。Windows 没有官方图形端，常见做法是社区客户端或直接命令行运行核心。Shadowrocket 等第三方客户端也支持 sing-box 格式的订阅，可以按使用习惯挑，具体对比见 Clash 客户端横向对比 2026。
机场只提供 Clash 格式订阅时，有两条路：一是让机场后台直接生成 sing-box 格式（现在多数都支持），二是用 sub-store 或 subconverter 做一次格式转换再导入。转换工具的参数名和输出细节时有变化，以各自文档为准。
四、分流规则的组织方式
规则是 sing-box 最花心思、也最能体现「组织能力」的部分。先立心智模型，再谈顺序。
4.1 心智模型：自上而下，命中即停
route.rules 是一个数组，连接进来后从第一条开始逐条比对，命中第一条符合的就执行，不再往下看；全部没命中，交给 route.final 指定的出站。所以写规则的本质是排序：越具体的、越需要优先处理的放越前面，越大而化之的兜底放越后面。顺序写反是规则「不生效」的第一大原因，而不是规则本身写错。
规则匹配的弹药主要来自 rule-set：把成千上万个域名或 IP 段打包成二进制 .srs 文件，配置里只引用它的标签。规则集要在 route.rule_set 里先定义，远程集的定义长这样：
"rule_set": [
{
"type": "remote",
"tag": "geosite-cn",
"format": "binary",
"url": "规则集仓库里对应文件的 raw 地址",
"download_detour": "proxy",
"update_interval": "24h"
}
]download_detour 解决一个先有鸡还是先有蛋的问题：规则集文件本身往往也要走代理才能下载，所以要指明用哪个出站去拉它。社区维护的规则集仓库有几家，域名分类和 IP 库各选一家持续维护的用即可，不必混搭。
4.2 一个可用的组织顺序
下面这套顺序覆盖大多数人的日常需求，后文逐条解释为什么这样排：
"route": {
"rules": [
{ "action": "sniff" },
{ "protocol": "dns", "action": "hijack-dns" },
{ "rule_set": "geosite-category-ads-all", "action": "reject" },
{ "ip_is_private": true, "outbound": "direct" },
{ "rule_set": ["geosite-cn", "geoip-cn"], "outbound": "direct" },
{ "rule_set": "geosite-netflix", "outbound": "stream" }
],
"final": "proxy",
"auto_detect_interface": true,
"default_domain_resolver": "local"
}- 前两条是动作规则，不是分流规则。
sniff把连接的真实域名嗅探出来，后面的域名规则才有东西可匹配；hijack-dns把系统里的 DNS 查询劫持进自己的 DNS 模块。这两条的位置必须在最前面。顺带纠正一个老写法：早期版本把嗅探开关写在入站配置里（sniff字段），现在已经统一成路由规则的动作，老配置迁过来时记得挪位置。 - 阻断类紧随其后。广告规则集用
action: "reject"直接拒绝。这里同样有个新旧变化：以前靠一个block类型的出站来拦截，新版本已把block出站标记弃用，拦截统一改用规则的 reject 动作，还在往出站列表里放 block 的，属于该更新的写法。 - 局域网与国内直连放在中段。
ip_is_private让打印机、NAS、路由器后台这类本地地址不绕远路；国内域名与 IP 集合并成一条直连，写在前面几个「特殊处理」之后、兜底之前。 - 定向分流按需插队。某个流媒体要走特定落地、某个服务要走自建节点，就在
final之前给它单开一条，指向对应的策略组；这类规则越具体越要靠前。 final是价值观。剩下的流量默认走代理还是默认直连，取决于你装这套东西的目的——本文默认前者。没有 final 也能跑（有内置默认），但显式写出来，配置的意图才完整。
更复杂的条件用逻辑规则组合：一条规则里可以嵌套 and / or 子规则，也可以用 invert 取反，比如「目的地非国内、且端口是 8443」这类复合判断。日常用到的机会不多，知道有这层能力、需要时查文档即可，不必硬背字段。
4.3 从 Clash 迁过来的人看这张表
概念是一一对应得上的，只是组织方式变了：
| Clash 里的东西 | 在 sing-box 里对应 |
|---|---|
| proxies | outbounds 里的节点条目 |
| proxy-groups | selector / urltest 类型的出站 |
| rules | route.rules |
| rule-providers | route.rule_set 定义的规则集 |
| dns 段 | 顶层 dns 块（服务器写法已改版，见 3.3） |
| tun 段 | inbounds 里 type: "tun" 的条目 |
愿意手迁的，按表对着改一遍就熟悉了；嫌麻烦的用转换工具生成初稿，再人工过一遍规则顺序和 DNS 部分——自动转换最容易丢的就是这两处细节。
五、日志与排错：先校验，再看日志，最后动配置
sing-box 排错有一条固定路线：配置起不来，先用 check 看校验报错；运行中行为不对，把日志级别临时调到 debug，复现一次问题，看那条连接实际命中了哪条规则、从哪个出站出去、DNS 是谁解析的。日志会把这三件事都打出来，绝大多数「规则不生效」看到日志就破案了，不需要靠猜。基于这条路线，整理一份排错清单：
| 现象 | 先查什么 | 常见原因 |
|---|---|---|
| 进程启动即退出 | sing-box check 的报错行 | 字段用了已改名/已删除的旧写法（如 DNS 的 address、TUN 的 inet4_address）；或 JSON 多了逗号 |
| 规则像没写一样 | debug 日志里这条连接命中的规则 | 顺序在前的大类规则先命中了；或规则里引用的 rule-set 标签与定义处拼写不一致 |
| 规则集加载失败、相关规则全落空 | 启动日志里 rule-set 的下载记录 | 远程集地址失效，或没配 download_detour 导致在本地网络拉不到文件 |
| 国内站点也绕了代理、变慢 | 日志里该连接的出站 | cn 规则集没加载成功，于是落到 final；或这条连接走的是 IP 匹配、域名嗅探没开 |
| DNS 泄露测试不通过 | dns 的 final 与远程服务器的 detour | 远程解析没走代理；或浏览器开了自己的安全 DNS 绕过了系统 |
| 开 TUN 后打印机、NAS 访问不了 | route 规则与 TUN 的排除项 | 缺 ip_is_private 直连规则；或用 TUN 的 route_exclude_address 把局域网段排除在接管之外 |
| 更新订阅后自己加的规则没了 | 你编辑的是哪个文件 | 客户端更新订阅会整份覆盖配置；手写规则应单独成文件，用 sing-box merge 合并，或在客户端里用覆写功能维护 |
| 某些软件死活不走代理 | 该软件的流量有没有进 TUN | 没开 TUN 时只有认系统代理的软件才走；要么开 TUN，要么给该软件单独指定 mixed 端口 |
两个和规则集打交道时顺手的命令：自己维护规则源时，用 sing-box rule-set compile 把 JSON 规则源编译成 .srs 二进制；排查某个规则集到底含不含某域名，用 sing-box rule-set match 直接测。都比对着日志猜要快。
最后留一句组合思路：sing-box 擅长的是「一台设备上的精细分流」，如果你还需要整网段的隧道打底（比如路由器层面先有一条稳定通道），可以把 WireGuard 自建 VPN 教程 的通道和它叠起来用，前者管连通、后者管分流，两边各干最擅长的部分。
延伸阅读：
- 科学上网协议对比 2026 — 节点协议怎么选
- 3X-UI 自建代理完整教程 — 面板流自建节点
- WireGuard 自建 VPN 教程 — 隧道打底的另一种解法
- Clash 客户端横向对比 2026 — 图形客户端怎么挑
- iOS 代理完整指南 2026 — 苹果设备上的客户端与账号问题