随着代理生态的持续演进，由 SagerNet 团队主导开发的开源代理平台 sing-box 凭借其极致轻量化的内存表现、原生全协议栈支持（如原生 ShadowTLS、TUIC v5、Hysteria2、VLESS Reality 等）以及出色的跨平台统一内核，迅速成为了全球技术爱好者与高阶用户的旗舰之选。然而，与传统基于 YAML 格式的客户端不同，sing-box 采用了严密的 JSON 树状结构作为核心配置语言。很多从传统客户端迁移过来的新手，在面对嵌套繁琐的 inbounds、outbounds、route 与 dns 顶层字段时，往往感到无从下手，稍有括号闭合不当就会导致核心解析报错退出。本文将系统拆解 sing-box 核心配置文件的设计哲学、四大核心模块的语法骨架与实战调试路径。
一、sing-box 的核心设计哲学：正交解耦与管道模型
要轻松看懂 sing-box 的配置代码，首先必须掌握其底层的抽象管道模型（Pipeline Model）。
在传统的代理软件中，DNS 模块往往深埋在路由或入站规则内部，逻辑边界非常模糊，导致很多高阶分流逻辑难以表达。而 sing-box 采取了极其彻底的“正交解耦”架构设计理念，将网络流处理的全流程拆解为四个彼此独立但严密联动的离散阶段：
第一阶段是入站监听层（Inbounds）。负责监听本地物理系统或局域网的网络流量。例如，在操作系统底层开启一个全功能的高性能 TUN 虚拟网卡，或者在本地绑定监听 SOCKS5、HTTP 混合代理端口。入站层在截获原始数据包之后，会提取出底层协议报头，将其无损封装为统一的抽象会话元数据（Metadata Session），并为该数据流贴上唯一的入站标签（Inbound Tag），随后递交给路由引擎。
第二阶段是 DNS 处理中枢（DNS Engine）。sing-box 创新性地将 DNS 提升为系统的一等公民（First-Class Citizen）。DNS 模块自身拥有完全独立的解析服务器池、专属分流规则链以及基于内存哈希维护的 Fake-IP 虚拟地址池。它既可以作为普通入站流量的域名解析后端，又可以直接作为一个独立的虚拟入站或出站端点参与全局流转，实现了对域名解析流动的全生命周期掌控。
第三阶段是路由判定链（Route Engine）。这是整个客户端的决策大脑。路由引擎接收到携带完整元数据（源 IP、目标域名、目的端口、入站标签、进程名、协议类型等）的会话后，自顶向下严格匹配用户预定义的规则列表。路由引擎在毫秒之间完成评估，最终输出一个不可更改的仲裁结果——即决定将该会话派发给哪一个特定的“出站标签（Outbound Tag）”。
第四阶段是出站交付层（Outbounds）。这是真正的流量实体出口。出站不仅可以是具体指向海外节点的各种代理协议（如 VLESS、Shadowsocks、Hysteria2、TUIC 等），还可以是系统的直接出口（DIRECT）、安全丢弃（BLOCK）、DNS 专用出站，或者由多个节点编组而成的动态调度策略组（如手动选择 Selector、延迟自动优选 URLTest 等）。
数据包在这个四元体系中像工业流水线一样单向流动，职责极其分明，从架构上有效隔离了不同功能模块之间的耦合与副作用。
二、四大顶层模块的语法规范详解
一个完整合法的 config.json 文件必须包含以下四个核心顶级键：
1. Inbounds（入站配置）
最常用的桌面端入站方式是同时开启混合代理端口与系统级 TUN 虚拟网卡：
{
"inbounds": [
{
"type": "mixed",
"tag": "mixed-in",
"listen": "127.0.0.1",
"listen_port": 2080
},
{
"type": "tun",
"tag": "tun-in",
"inet4_address": "172.19.0.1/30",
"auto_route": true,
"strict_route": true,
"stack": "system",
"sniff": true
}
]
}在这里，strict_route: true 保证了操作系统不会发生漏网直连，sniff: true 开启了精准的流量嗅探（用于在数据包进入时提取 TLS SNI 或 HTTP Host 域名）。
2. Outbounds（出站定义与策略组）
出站列表中定义所有可以转发流量的目的地。除了单个节点外，最重要的就是策略选择组：
{
"outbounds": [
{
"type": "selector",
"tag": "proxy",
"outbounds": ["node-hk", "node-us", "direct"]
},
{
"type": "urltest",
"tag": "auto-select",
"outbounds": ["node-hk", "node-jp", "node-sg"],
"url": "https://www.gstatic.com/generate_204",
"interval": "3m"
},
{
"type": "direct",
"tag": "direct"
},
{
"type": "block",
"tag": "block"
}
]
}3. Route（路由链与规则集）
路由模块决定流量的具体去向。其最强大的特性是对外部编译规则集（.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"
}
],
"rules": [
{ "inbound": "dns-in", "outbound": "dns-out" },
{ "protocol": "dns", "outbound": "dns-out" },
{ "rule_set": "geosite-cn", "outbound": "direct" },
{ "ip_is_private": true, "outbound": "direct" }
],
"final": "proxy",
"auto_detect_interface": true
}
}这里 final: "proxy" 即为最后的兜底规则，所有未命中的请求全部派发至代理策略组。
4. DNS（独立解析中枢）
sing-box 的 DNS 模块支持定义多个上游解析服务器并进行规则绑定：
{
"dns": {
"servers": [
{
"tag": "remote-dns",
"address": "tls://1.1.1.1",
"detour": "proxy"
},
{
"tag": "local-dns",
"address": "223.5.5.5",
"detour": "direct"
}
],
"rules": [
{ "rule_set": "geosite-cn", "server": "local-dns" }
],
"final": "remote-dns",
"strategy": "ipv4_only"
}
}通过 strategy: "ipv4_only"，可以彻底根除 代理环境中的IPv6泄漏与Happy Eyeballs回退控制 中提到的潜在风险。
三、从零组装可运行配置的标准步骤
在桌面端（如使用 sing-box 官方二进制或配合开源 GUI 外壳）部署配置时，应当遵循以下四个标准实施步骤：
第一步是建立最小可用骨架。不要一上来就从网络上复制动辄上千行的复杂模板，而是从一个只包含一个 SOCKS 入站、一个 DIRECT 出站和一个远端节点的极简配置开始。确保每一对大括号与中括号完全匹配闭合，验证基础语法能够被程序无错读取。
第二步是引入 TUN 模式与自动接口探测。在路由模块中务必加入 auto_detect_interface: true 参数。这一配置极其关键，它指示 sing-box 内核在后台持续监听操作系统的网络接口跃迁事件。当笔记本电脑从有线以太网物理断开并漫游切换到无线 Wi-Fi 信号时，内核能够迅速感知链路变化，自动完成 TUN虚拟网卡接管默认路由的底层原理：路由表权重跃点与回环规避 中提到的虚拟网卡绑定重定向，彻底消灭切换网络后的假死断连现象。
第三步是挂载编译好的二进制规则集。参考 GeoSite规则集的结构编译与匹配开销：大型规则列表的内存与匹配性能调优 的优化建议，优先使用官方预编译的 .srs 紧凑二进制格式，避免客户端在启动时进行沉重的文本解析与前缀树展开，从而显著降低启动时的物理内存开销。
第四步是配置域名嗅探与元数据还原。在 inbounds 的 TUN 配置中启用 sniff: true 与 sniff_override_destination: true。当某些未适配系统代理的老旧应用程序直接向纯 IP 发起连接时，嗅探器能够在 TLS Client Hello 握手包中提取真实的 SNI 域名，将原本的盲目 IP 路由精准还原为域名级分流规则，大幅提升分流命中率。
四、配置语法检查与高频排错方案
在启动 sing-box 时，如果遇到控制台闪退或报错，应当按照以下流程定位修复：
第一步是使用内置命令执行静态语法校验。在终端中运行 sing-box check -c config.json。sing-box 拥有非常严密的编译时类型检查器，它能够精确定位到某一行、某一列的 JSON 逗号缺失、类型不匹配或标签引用断裂，并输出清晰的英文错误堆栈。
第二步是排查策略组循环引用与孤儿 Outbound。检查 route.rules 中的每一个 outbound 标签是否都在 outbounds 列表中真实存在；检查 Selector 或 URLTest 策略组内部引用的节点名称是否完全对应，避免出现死锁。
第三步是结合日志级别定位分流偏离。在顶级配置中加入 "log": { "level": "debug" }，在终端启动运行。sing-box 会在控制台高频打印每一条网络连接的完整生命周期：从哪个入站被捕获、命中了哪一条路由规则、最终被送往哪个出口，从而彻底消除配置死角。结合 分流规则匹配顺序与短路求值原则：避免代理规则被前置直连覆盖 确立的优先级，确保每一个关键域名都能被稳定调度。