sing-box 配置文件怎么写：从最小模板开始

更新于 2026-11-06 · bocchi.icu

简答：sing-box 配置文件通常保存为 JSON，建议先写一个只包含 mixed 入站、direct 出站和 route.final 的最小配置，再逐步加入节点、DNS、分流或 TUN。先用本机 sing-box 执行 check 校验，确认通过后再启动；配置字段会随版本变化，遇到未知字段应以当前版本配置参考为准。

定义：sing-box 配置文件是描述流量如何进入客户端、通过哪个出站连接以及如何按规则分流的 JSON 文件。

先看最小配置：不要一开始就加入节点、DNS 和 TUN

sing-box 使用 JSON 配置文件，官方配置结构包含 log、dns、inbounds、outbounds、route 等顶层字段。刚开始写配置时，不建议同时加入订阅转换、规则集、TUN 和多个协议节点；先验证 JSON 结构与本地代理入口，排错范围会更小。参考官方配置总览。

下面这个模板只用于验证“配置能否被读取、mixed 端口能否监听、请求是否走 direct”。它不包含远程节点，因此不能证明某个代理线路可以连接。

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

模板中，inbounds 是流量进入 sing-box 的入口；mixed 可同时提供 SOCKS 和 HTTP 服务。outbounds 是流量离开的出口；direct 表示直接连接。route.final 指定没有匹配其他规则时使用的出站标签。字段含义可分别对照mixed 入站文档、direct 出站文档和route 文档。

JSON 写法的四个硬规则

对象使用大括号：例如 {"type":"direct"}；数组使用方括号，例如 [{...}]。
字段之间用逗号：最后一个字段后不要加多余逗号，否则可能无法通过解析。
字符串使用双引号：不要把 JSON 中的双引号改成中文引号，也不要使用单引号代替。
不要直接写注释：普通 JSON 不接受 // 注释 或 /* 注释 */。如果需要保留说明，先写在配置外部，或使用编辑器的注释功能但不要保存进最终 JSON。

建议先复制最小模板，确认能校验后一次只增加一个模块。每次修改前保留一份可恢复的副本，例如把 config.json 复制为 config.json.bak。

从空白文件到通过校验：按顺序执行

确认本机版本：在终端执行 sing-box version。如果命令不存在，先确认程序是否已加入 PATH；图形客户端则在其核心或关于页面查看版本。本文不固定某个版本号，因为字段可能随版本调整。
保存配置：将模板保存为 config.json，文件编码使用 UTF-8，文件名和实际路径以你的系统或客户端为准。
执行检查：在配置文件所在目录运行 sing-box check -c config.json；如果当前构建的帮助信息显示参数形式不同，应以 sing-box check --help 为准。官方配置文档明确提供了 sing-box check、format 和 merge 命令。
格式化可选：确认已经备份后，可运行 sing-box format -w -c config.json。格式化前不要覆盖唯一副本。
启动验证：运行 sing-box run -c config.json。看到程序保持运行且没有立即退出，通常说明配置已经被读取；这不等于网络代理一定可用。
测试本地入口：将应用的 HTTP 或 SOCKS 代理指向 127.0.0.1:2080，再访问一个普通网页或使用系统网络测试工具。若请求日志没有变化，先检查应用是否真的使用了该端口。

如果你的配置由多个文件组成，可以先查阅当前版本的命令帮助，再考虑 sing-box merge output.json -c config.json -D config_directory。不要把不同版本生成的配置片段直接混合后使用。

加入节点时，哪些字段必须替换

最小模板中的 direct 只是直连出口。要使用远程节点，需要在 outbounds 中新增对应协议对象，并把 route.final 改为该对象的 tag。官方出站列表包含 direct、Shadowsocks、VMess、Trojan、VLESS、WireGuard、Hysteria2、Selector 和 URLTest 等类型，但每种类型需要的字段不同，不能只改 type 就运行。可先查看官方出站类型列表。

以下内容只能作为字段位置示意，不能直接连接，因为占位符必须替换成服务端实际提供的值：

{"type":"vless","tag":"proxy-out","server":"替换为服务器地址","server_port":443,"uuid":"替换为实际 UUID"}

必须核对：type、tag、服务器地址、端口、身份凭据，以及 TLS、传输层或协议专属字段。
tag 要唯一：例如 proxy-out 只能对应一个出站，route.final 或路由规则引用的名称必须完全一致。
不要猜字段：从其他客户端复制的配置不一定能直接用于 sing-box；应按当前版本对应协议页面重新映射。
安全边界：不要把真实 UUID、密码、私钥或订阅地址发布到公开页面、工单或截图中。

DNS、route 和 rule_set：先理解关系，再扩展

dns 用于定义 DNS 服务器、DNS 规则和默认 DNS。route 用于决定请求使用哪个出站，rule_set 则可以作为路由匹配条件。刚开始排查时，可以暂时不加入复杂 DNS 规则和远程规则集，先用最小配置确认入口、出站和端口都正常。

一个概念性结构如下：{"dns":{"servers":[{"tag":"local-dns","address":"local"}],"final":"local-dns"},"route":{"rules":[{"domain_suffix":["example.com"],"action":"route","outbound":"direct-out"}],"final":"proxy-out"}}。这段示意中的 DNS 服务器写法、规则动作和可用字段必须结合安装版本的官方文档核对，不建议未经验证直接复制到生产配置。

路由规则通常按列表顺序参与匹配，final 负责没有命中规则时的默认出站。官方 route 文档也说明，空的 final 会使用第一个出站，因此建议显式填写标签，避免新增出站后默认行为发生变化。DNS 字段和缓存、解析策略等变化较多，修改前应查看官方 DNS 文档。

TUN 配置为什么不适合和基础模板一起写

TUN 会改变系统流量的接管方式，通常还涉及系统权限、路由、DNS 劫持、自动检测网卡和回滚。它不是“把 mixed 换成 tun”这么简单。官方文档将 TUN 列为独立入站类型，桌面客户端也把 TUN 透明代理作为平台功能之一；具体权限和字段要按系统及客户端实现核对。

建议先使用本地 mixed 入口验证配置，再单独复制一份文件加入 TUN。若加入 TUN 后断网，优先回滚到备份文件，关闭 TUN 或停止 sing-box，恢复系统代理和 DNS 设置，再检查 route.auto_detect_interface、DNS 劫持、权限和端口冲突。不要在尚未通过基础配置验证时同时修改 TUN、DNS 和分流。

常见报错与下一步

现象	常见原因	处理顺序
JSON 解析失败	逗号、括号、引号或注释错误	先用编辑器格式化，再运行 `sing-box check`，逐段删除最近新增内容。
unknown field 或未知字段	字段属于其他版本、拼写错误或已迁移	执行 `sing-box version`，对照当前版本官方配置页面，不要盲目改成相似字段。
重复 tag	多个入站或出站使用同名标签	给每个对象改成唯一 tag，并同步修改 route 引用。
端口已被占用	2080 已被其他程序监听	更换 `listen_port`，或停止占用端口的程序后重新启动。
配置通过但无法连接	校验只证明结构和字段可读，不证明节点、DNS 或网络可达	先用 direct 模式测试本地入口，再逐项核对服务器地址、端口、凭据、TLS 和 DNS。

发布前自查清单

是否确认了正在运行的 sing-box 版本，而不是只看教程发布日期？
是否保留了能通过 check 的备份配置？
所有 tag 是否唯一，route 引用是否完全一致？
节点地址、端口、UUID、密码和 TLS 参数是否来自可信的配置来源？
是否先验证 mixed 本地代理，再加入 DNS、规则集和 TUN？
配置通过 check 后，是否仍然单独测试了端口监听、DNS 解析和实际连接？

本文是面向配置排查的使用指南，不是 sing-box 官方页面；sing-box 的版本、字段和平台行为应以当前官方文档为准。

常见问题

sing-box 配置文件必须叫 config.json 吗？

不一定。sing-box 使用 JSON 配置内容，文件名可以因客户端或启动参数而不同；如果使用命令行，应通过 -c 指定实际路径。为了便于识别，新手通常可以保存为 config.json。

Clash 配置文件能直接改成 sing-box 配置吗？

通常不能直接改名使用。两者的顶层字段、入站、出站、路由和规则集结构不同，需要使用兼容的转换工具或按 sing-box 当前官方字段重新编写，转换后仍要执行 check。

配置通过 check，为什么还是连不上？

check 主要用于检查配置能否被解析和识别，不代表远程服务器可达、凭据正确、DNS 正常或系统流量已经进入客户端。应先验证本地 mixed 端口，再检查节点参数、DNS、路由和客户端代理设置。

route.final 应该填什么？

填写某个出站的 tag，例如 direct-out 或 proxy-out。它表示没有命中其他路由规则时采用的默认出站。建议显式填写，不要依赖空值时使用第一个出站的行为。

加入 TUN 后无法上网怎么办？

先停止 sing-box 或关闭 TUN，恢复之前能通过 check 的配置，再确认系统代理、DNS 和网卡路由是否恢复。之后一次只改一个变量，依次检查权限、端口、DNS 劫持、自动检测网卡和 route 设置。