sing-box 配置文件入门：JSON 结构与最小可用配置

梯子岛编辑部 · 更新于 2026-10-09

教程V2Ray 与 sing-box 教程难度：高级约 8 分钟读完

sing-box 的配置是一份 JSON 文件，顶层按职责分成几大块：谁来记日志、怎么解析域名、流量从哪里进来、从哪里出去、中间按什么规矩分派。把这五件事分清，sing-box 配置就从“一堵字墙”变成了五个可以单独检查的小房间。下面按这个顺序带你读一遍，最后再讲怎么改、怎么验。

先搞清楚：这份 JSON 到底在回答什么问题

一份能跑起来的配置，本质上是在回答五个问题：

这张表也是排错顺序：一条连接失败，先问“进来了吗”（入站），再问“被分派到哪了”（路由），最后问“出去的路通不通”（出站）。DNS 和日志则是贯穿全程的两个帮手。

具体字段名与取值，梯子岛一律以官方文档为准。内核的更新节奏很快，页面上出现的写法可能比你手里的版本新，也可能比它旧。

sing-box 配置文件的骨架长什么样

下面是一份结构示意，只展示各块的位置和嵌套关系，里面的内容是占位，不能直接运行：

{
  "log": { },
  "dns": { },
  "inbounds": [ ],
  "outbounds": [ ],
  "route": { }
}

注意三个形状上的细节：

• log、dns、route 是对象，用花括号；
• inbounds、outbounds 是数组，里面可以放多个条目，用方括号；
• 数组里的每个条目靠 type 说明它是什么类型，靠 tag 给它起个名字，别的地方就是通过这个名字引用它的。

这个 tag 是整份配置里的“连线”。路由说“把这类流量交给某某出站”，写的就是那个出站的 tag；拼错一个字母，这条连线就断了。

动手写一份最小的配置：先让流量进得来、出得去

最小可用的思路是：开一个本机入站接收流量，准备一个出站，再让路由把流量交给它。为了不依赖任何真实节点，我们先用“直连”做出站，验证内核本身能起来：

{
  "log": { "level": "info" },
  "inbounds": [
    {
      "type": "mixed",
      "tag": "in-local",
      "listen": "127.0.0.1",
      "listen_port": 2080
    }
  ],
  "outbounds": [
    { "type": "direct", "tag": "out-direct" }
  ],
  "route": { "final": "out-direct" }
}

这只是示意，用来体会五块之间怎么连。读它的方式是：

1. 入站监听本机回环地址，意思是只接受本机程序的连接，局域网里的其他设备连不进来；
2. 出站的类型是直连，不经过任何代理；
3. 路由的兜底去向指向那个出站的 tag。

字段是否这样拼写、哪些取值可用，请对照你所用版本的文档。示意里的端口号是随手写的，换成你机器上没被占用的即可。

确认这份最小配置能启动之后，再把 out-direct 之外的真实节点一项项加进出站，这样出错时你知道问题出在新加的那一项。

把真实节点加进来：出站里要补哪些信息

节点信息通常来自你的服务提供方，格式可能是分享链接，也可能是现成的 JSON 片段。要把它放进配置，需要弄清三件事：

• 协议类型：决定出站的 type。你的客户端内核是否支持该协议，可以去梯子岛的协议 × 客户端支持矩阵核对；
• 服务器与端口：节点的基本寻址信息；
• 协议专属项：例如认证信息、传输方式、TLS 相关设置，各协议要求不同。

如果手里只有分享链接，不要靠肉眼拆字段。用梯子岛的节点链接解析工具可以先在浏览器本地看清每一段是什么，再对着官方文档填进去。需要把别的格式转过来时，可以试试节点转换工具，但转换结果要当作草稿，逐项复核。

还有一条要记住：已被官方弃用的写法，不要再抄。比如 WireGuard 在较新版本里改用 endpoint 的写法，旧的出站写法已进入弃用；ShadowsocksR 早已从内核里移除。看到老教程用到它们，说明那篇文章可能已经过时。

路由与 DNS：为什么这两块最容易写错

路由块决定“什么流量走哪条路”，通常由若干条规则加一个兜底组成。思考顺序可以这样走：

1. 先定兜底：没被任何规则命中的流量，默认直连还是默认走代理；
2. 再加例外：哪些域名、哪些地址段要反着来；
3. 最后才考虑进阶条件，例如按进程区分。

DNS 块则和路由相互牵连：域名先被解析成什么，往往决定了它会命中哪条规则。所以改了 DNS 之后，要回头把路由复查一遍，反之亦然。两者的细节可以对照梯子岛已有的 Clash DNS 设置一文理解思路，但两边的字段不通用，不要把 YAML 里的写法搬过来。

sing-box 配置在不同端上不完全通用

同一份配置放到不同平台，能用的选项并不一样。官方文档里有一条值得提前知道：苹果设备上的虚拟网卡由系统的网络扩展提供，auto_route、stack 这类桌面端常见的 tun 选项在那里没有实现；按进程名分流也只在 macOS 独立版和越狱的 iOS 版上可用。

所以你在电脑上调好的配置，原封不动导进手机，可能出现“某项设置被忽略”的情况。原则是：用哪个平台，就以那个平台的官方客户端文档为准。各端官方客户端的入口见 sing-box 客户端档案，导入与使用的步骤见 sing-box 客户端使用教程。

改完以后怎么确认没写错

别等到“连不上”才发现问题，按这个顺序检查：

1. 先查语法：用能做 JSON 校验的编辑器，或者内核自带的配置检查功能，把括号、逗号、引号的错误先清掉；
2. 再查引用：每个被路由、DNS 引用的 tag，在出站里都要真的存在；
3. 再看启动日志：把日志详细程度临时调高，看内核是否报字段不认识或被弃用；
4. 最后验证出口：连上之后，用IP 与 DNS 检测导航里的站点看出口地址是否按预期变化。

改动时养成两个习惯：一次只动一块；动手前先备份一份能用的旧文件。排错的时候，二分法比通读更有效。

手写配置之外，还有哪些省力的路

不是每个人都需要手写 JSON。如果你的目标只是“把订阅导进去用起来”，图形客户端更省心：官方提供了安卓、苹果设备和桌面系统的图形界面，社区里也有把 sing-box 内核封装起来的客户端。选 singbox gui 类工具时，看三件事：它是否仍在维护、你的平台是否有对应版本、它读取的是配置文件还是订阅链接。

想弄清 sing-box 与 Clash 系内核在配置思路上的差别，可以读 sing-box 与 Mihomo 对比。官方文档汇总在官方文档导航，需要下载内核或客户端时，请只走官方渠道，入口集中在 GitHub 项目导航。

下一步怎么走

• 想先把东西跑起来：读 sing-box 客户端使用教程，用图形客户端导入配置；
• 想系统学字段：打开官方文档，从你正在用的那个块读起，不必一次读完；
• 手里是别的格式的节点：先用节点转换工具出草稿，再回到本文的“改完以后怎么确认没写错”逐项复核；
• 想对比内核取舍：看 sing-box 与 Mihomo 对比。

接着读

• 客户端 · sing-box 是什么？内核、官方客户端与各平台入口
• 对比 · sing-box 与 Mihomo 内核对比：配置格式与生态
• 教程 · sing-box 官方客户端怎么用？导入配置与订阅的基本做法
• 教程 · Clash 配置文件怎么看？YAML 结构与常用字段讲解
• 教程 · Hiddify 使用教程：导入订阅与连接
• 教程 · Hysteria2 客户端配置：导入节点与常见填写项

文中出现的术语

• sing-box 内核
• 代理内核
• Mihomo
• 节点链接 URI
• 分流
• TLS
• WebSocket
• YAML